ObjectivePHP Documentation

[jheussler]

ObjectivePHP RFC: ObjectivePHP Documentation

• Version: 1.0
• Date: 2018-03-16
• Author: Jordan Heussler, [email protected]
• Status: Draft

Summary

For a better understanding of ObjectivePHP, we need to strengthen the documentation available to our users.
I suggest a website with components' / integrations' documentations gathered from all O-PhP repositories automatically, maintained up to date with a hook on releases, fully auto-generated.

Proposal

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in RFC 2119.

One centralised website with every components' documentations and some integration exemples.
This website will be generated into html content from PHP Code and Readme from repositories with the help from a github hook.

For the PHP doc perspective, no need to create another parser and we will be using one already existing. To handle specific documentation (integration, examples, details about some features) we need to fill a readme file with specific content : title, sections etc, writted in markdown.

Description

Photo

Doc API - PHPDoc

• must : public methods and functions, properties, class
• should : protected and private methods

Readme.md

• summary
• contribute
• link to doc

Docs tree

• /docs/index.md
• /docs/01.quick-start.md
• /docs/02.detailed-usage.md
• /docs/03.config-directives.md
• /docs/04.api-doc.md
• /docs/05.faq.md

Backward Incompatible Changes

None

Proposed ObjectivePHP Version(s)

Targeted framework (and components) version to strictly apply these standards is 2.0.0.

RFC Impact

To Components

No impact

To Packages

No impact

To Workflow

No impact

To Configuration

No impact

Future Scope

None

Proposed Voting Choices

As all changes are bundled in one vote it require a 2/3 majority.

Links to external references, discussions, issues or RFCs

PHP doc parser : https://github.com/martinsik/php-doc-parser