Guides Laravel Package

Getting Started

Start by installing the package via Composer: composer require phpdocumentor/guides --dev. The entry point is the CLI command phpdocumentor guide:render (often aliased as phpdocumentor depending on setup), which expects a guides.yml config file in your project root. Begin with a minimal config that specifies an input directory (e.g., docs/) and output directory (e.g., build/docs/). Your first .rst file should be index.rst, using standard reStructuredText syntax—think headings, lists, and basic formatting. Run the command, inspect the generated HTML in build/docs/, and verify that rendering succeeds. This verifies the core pipeline: source → AST → HTML.

Implementation Patterns

• Modular Docs Workflow: Organize content into docs/ subdirectories (e.g., usage/, api/, contributing/) and link them via .. toctree:: directives. This mirrors how large open-source projects structure their documentation (e.g., Symfony, Laravel’s own docs historically).
• Custom Environments: Define multiple environments (e.g., dev, production) in guides.yml to control behavior like link checking, analytics inclusion, or versioning.
• Custom Directives & Nodes: Extend Guides by implementing NodeVisitor and Directive classes. For example, inject a .. envvar:: directive to highlight environment variables with syntax highlighting and tooltips in HTML output. Register these via guides.yml under extensions or via environment-specific config.
• CI Integration: Add phpdocumentor guide:render --env=production to your CI workflow. Use the --watch flag (during local dev) and --output-dir for artifact publishing. For versioned docs, generate docs per release tag and store outputs in per-version subdirectories (e.g., docs/v1.0/, docs/v2.0/).
• Renderer Swapping: Swap HTML for PDF or Markdown using alternative renderers (e.g., phpdocumentor/guides-renderer-html vs. future renderer packages), enabling reuse of the same reST source across distributions.

Gotchas and Tips

• reST Quirks: Guides uses docutils-style reST, not Sphinx. Avoid Sphinx-specific features (e.g., :ref: roles) unless you implement them as custom extensions. Whitespace and indentation are strict—a single misaligned line can break parsing silently.
• Path Resolution: Relative paths in .. include:: or image directives are resolved relative to the current document, not the project root. Use :show-inheritance: and .. only:: directives carefully—they behave differently than in Sphinx.
• Error Masking: CLI output can be opaque. Enable verbose mode (-vvv) to see internal parsing errors or renderer failures. Check build/ log files for full stack traces.
• Extensibility Hook Points: The most powerful extension points are NodeVisitorInterface (post-parse transformations) and DirectiveInterface (custom syntax). Register them via DI container in guides.yml or via environment-aware bootstrap files.
• Performance Pitfalls: Large docsets may build slowly due to AST traversal. Profile with Xdebug or disable optional features (e.g., link validation in dev builds) via config to keep iteration fast.