ObjectivePHP Documentation #5
Description
ObjectivePHP RFC: ObjectivePHP Documentation
- Version: 1.0
- Date: 2018-03-16
- Author: Jordan Heussler, jhe@opcoding.eu
- 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
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