This feature is EXPERIMENTAL. None of the features nor the API should be considered stable and may change without notice. There is no backwards compatibility promise for this part of the code as it is highly in development.
The Guide component was introduced as an experimental feature in phpDocumentor 3.1.
Guide generation is phpDocumentor's implementation for converting hand-written documentation into a static page integrated with the API Documentation. These share each other's Table of Contents in order for them to link to one another.
The design for the Guide Generation is based on the premise that we could support multiple input formats (RestructuredText, Markdown, Textile, etc); but in the first version RestructuredText is the only supported input format.
The code for rendering guides using RestructuredText-based documentation is based on, and with permission of, Ryan Weaver his work on the docs-builder package, combined with the RST-Parser by Doctrine (which is based off that of Gregwar).
The architecture of the Guides implementation revolves mainly around these 5 concepts:
- Kernel - the core orchestrator for parsing and rendering RestructuredText into the requested output format.
- Documents & Nodes - the broken down composition of a document, similar to an AST for code.
- Directives - Specialized sub-parsers that know how to deconstruct RestructuredText Directives into Nodes.
- (Output) Formats - Specialized functionality to render the parsed documents into a requested output format, such as HTML or LaTeX (for PDF generation).
- Renderers - services used to convert Nodes into pieces of output format, such as HTML