Getting Started

Install via Composer: composer require phpdocumentor/guides-restructured-text
Ensure phpdocumentor/guides is already installed and configured (this package is a parser/renderer plugin for Guides)
Create a .rst file (e.g., index.rst) in your docs/ directory using standard reStructuredText syntax
Add the directive .. guides:: to enable Guides-specific rendering if needed (though integration happens automatically)
Run your Docs build (e.g., phpdocumentor guide:build --directory=docs) — the .rst files will be parsed and rendered with full Guides theming and navigation

Implementation Patterns

Use .. include:: and .. literalinclude:: to modularize docs (standard reST, fully supported)
Leverage cross-references like :doc:docs/guide or `:ref:`label to generate internal links — works seamlessly with Guides’ navigation and sitemap
Define custom directives via RstParser::registerDirective() (typically in a service provider or bootstrap) to enforce team standards (e.g., .. tip:: → styled callout block)
Combine with phpdocumentor/guides themes: use --theme=custom and extend the default layout — .rst content fits naturally into sidebar, breadcrumbs, and section hierarchy
For CI/CD: include .rst files alongside Markdown; Guides will auto-detect format and route to the correct parser (no extra config needed)

❗ No standalone CLI: This package only integrates with phpdocumentor/guides — it cannot be used directly like sphinx-build. Always invoke via phpdocumentor guide:build
🧩 Directive support is partial: While core roles (:doc:, :ref:, :code:) and common directives (.. note::, .. code-block::) are supported, advanced Sphinx features (e.g., .. toctree::, .. automodule::) may require custom implementation or workarounds
🔍 Debug with --debug flag: Enables verbose logging for parsing errors — especially useful when custom directives fail silently
🛠 Extending? Extend phpdocumentor\guides\_RST\Parser\NodeVisitor\DirectiveHandlerInterface and register via the parser service — but note this requires overriding container bindings or patching phpdocumentor/guides config (breaking changes possible in minor releases)
⚠️ Anchor generation: Headings auto-generate anchors based on normalized text (e.g., My Section → #my-section), but non-ASCII characters may be stripped or transliterated — test cross-refs carefully for non-English titles