Guides Cli Laravel Package

Getting Started

Start by installing the CLI via Composer:

composer require --dev phpdocumentor/guides-cli

Then, create a simple guide structure (e.g., in docs/):

mkdir -p docs/_media docs/_static
echo "# Getting Started" > docs/index.rst
echo "This is my first guide." >> docs/index.rst

Render your guide to HTML with a single command:

vendor/bin/guides render docs docs/output

The first use case is generating static documentation from reStructuredText (RST) or Markdown (if using the appropriate extension) for distribution or hosting on a static site. The CLI wraps the underlying phpdocumentor/guides engine, offering a lightweight, dependency-contained way to render guides without building a full Symfony or Laravel app.

Implementation Patterns

• CI/CD Integration: Use the CLI in your CI pipeline to validate and build documentation on every push/PR. Example GitHub Actions step:

  - name: Build documentation
    run: vendor/bin/guides render docs docs/output --strict
  

• Theme Customization: Place custom themes in docs/_themes/, referencing them via --theme or config. Common pattern: override base templates (layout.html.twig) while inheriting default assets.

• Configuration File: Create docs/guides.yaml (or .yml) to configure navigation, sidebar, default extension (.rst/.md), and extension-specific settings (e.g., extensions: [phpdocumentor.guides.restructuredtext]).

• Watch Mode Workflow: Though not built-in, pair with entr or nodemon for local dev:

  find docs -type f | entr -c 'vendor/bin/guides render docs docs/output'
  

• Hybrid Doc + Site Builds: Combine with phpdocumentor/guides (core library) in a custom console command for advanced use cases like multi-version guides or database-backed content injection.

Gotchas and Tips

• PHP 8.1+ Required: Ensure your environment meets the minimum PHP version (^8.1). Common failure point: older GitHub Actions runners (e.g., ubuntu-latest pre-2023) default to PHP 8.0.

• Missing Extension Registration: If RST files fail to render, ensure phpdocumentor/guides-restructured-text is installed and explicitly enabled in config (e.g., extensions: [phpdocumentor.guides.restructuredtext]). Not automatically registered.

• Relative Asset Paths: All assets (_media, _static) must be at the source root (docs/). Paths are resolved relative to the source directory, not output — mistakes here cause broken images in output.

• Strict Mode: Use --strict for CI to fail on warnings (e.g., missing reference targets). In dev, omit for faster iteration.

• Cache Invalidation: Output is incremental; delete docs/output/ between major source changes to avoid stale artifacts.

• No CLI Help for Themes: vendor/bin/guides --help won’t list themes. List available themes via vendor/bin/guides list, and inspect phpdocumentor/guides source for known themes (e.g., default, readthedocs). Custom themes require Twig knowledge.

• Dependency Lock Risk: Since it depends on both guides:^1.0 and ^2.0 (via ||), ensure composer.lock resolves consistently. Use composer why-not phpdocumentor/guides 2.0 if version conflicts occur.