Guides Restructured Text Laravel Package

Product Decisions This Supports

• Enables standardization on reStructuredText across PHP-based documentation projects, unifying workflows without switching toolchains.
• Supports migration from Sphinx-based systems by leveraging existing .rst assets while integrating with phpDocumentor’s ecosystem for consistent builds and theming.
• Eliminates build-vs-buy trade-offs: avoids custom parser development by providing a maintained, extensible reST solution within existing PHP tooling.
• Aligns with roadmap goals for enterprise-grade documentation (cross-references, anchors, custom directives) that scales with complex technical content needs.

When to Consider This Package

• Adopt when:
  • Current documentation uses phpDocumentor and requires reST support (e.g., migrating legacy Sphinx docs).
  • Need for extensible directive handling (e.g., custom roles, output formats) within a PHP ecosystem.
  • Prioritizing consistency across multiple PHP projects using phpDocumentor for themeing and builds.
• Look elsewhere if:
  • Documentation is exclusively Markdown-based (e.g., MkDocs, Docusaurus).
  • Standalone reST processing is needed outside phpDocumentor (e.g., non-PHP projects or cloud-based tools).
  • Requirements are minimal (e.g., simple static sites where lightweight Markdown tools suffice).

How to Pitch It (Stakeholders)

Executives: "This package unifies our documentation workflow by natively supporting reStructuredText within our existing phpDocumentor ecosystem. It eliminates toolchain fragmentation, reduces maintenance costs, and ensures professional, navigable output for customers and developers—accelerating time-to-market for documentation while maintaining brand consistency."

Engineering: "It integrates seamlessly with phpDocumentor/guides, providing a battle-tested reST parser that handles directives, cross-references, and theming out-of-the-box. The extensible architecture lets us add custom features without forking core tooling, accelerating pipeline development while leveraging our PHP stack’s maturity and community support."