Phpdocumentor Markdown Laravel Package

Getting Started

Minimal Steps to Begin

1. Installation:

   composer require --dev saggre/phpdocumentor-markdown
   

   Ensure phpDocumentor is installed globally or via Composer (composer require --dev phpdoc/phpdocumentor).

2. First Run:

   phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown"
   

   This generates Markdown docs in the docs/ directory.

3. Composer Script (Optional): Add to composer.json for one-command generation:

   "scripts": {
       "docs:generate": "phpdoc --directory=src --target=docs --template=\"vendor/saggre/phpdocumentor-markdown/themes/markdown\""
   }
   

   Run with:

   composer docs:generate
   

4. Verify Output: Check docs/ for generated .md files (e.g., Home.md, classes/YourClass.md).

First Use Case: In-Repository Documentation

• Goal: Maintain API docs alongside code for GitHub/GitLab wikis or local reference.
• Workflow:
  1. Document classes/methods with PHPDoc blocks (e.g., @param, @return, @throws).
  2. Run composer docs:generate to update docs/ from src/.
  3. Commit docs/ to the repo (or symlink to a wiki/ folder for GitLab).

Implementation Patterns

Core Workflows

1. Documentation Generation

• Trigger: Post-code changes (e.g., via CI or pre-commit hooks).
• Command:

  phpdoc --directory=src --target=docs --template="vendor/saggre/phpdocumentor-markdown/themes/markdown" --cache=none
  

  • --cache=none forces regeneration (useful for CI).

2. CI Integration

• GitHub Actions Example (.github/workflows/docs.yml):

  name: Generate Docs
  on: [push]
  jobs:
    docs:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - run: composer install
        - run: composer docs:generate
        - uses: actions/upload-artifact@v3
          with:
            name: docs
            path: docs/
  

  • Output: Upload docs/ as an artifact or push to a gh-pages branch.

3. GitLab Wiki Sync

• Steps:
  1. Generate docs locally or in CI.
  2. Use GitLab’s API or manual upload to sync docs/ to the wiki.
  • Note: GitHub wikis do not support nested directories (links break).

4. Customizing Output

• Override Templates: Copy vendor/saggre/phpdocumentor-markdown/themes/markdown/ to templates/markdown/ and modify Twig files (e.g., header.md.twig, class.md.twig). Update the template path in composer.json:

  "scripts": {
      "docs:generate": "phpdoc --directory=src --target=docs --template=\"templates/markdown\""
  }
  

• Exclude Files: Use phpdoc.dist.xml to filter sources:

  <phpdocumentor>
      <files>
          <directory name="src" exclude="Tests/,Models/User.php"/>
      </files>
  </phpdocumentor>
  

Integration Tips

Laravel-Specific

1. Documenting Artisan Commands: Add PHPDoc to command classes (e.g., app/Console/Commands/YourCommand.php):

   /**
    * @param string $argument Description of argument.
    * @throws \Exception If validation fails.
    */
   protected function handle($argument): void
   

   The template will generate a dedicated .md file for the command.

2. Service Container Bindings: Document interfaces/contracts (e.g., app/Contracts/YourContract.php) to auto-generate API-like docs.

3. Event Listeners: Use @see tags to link events to listeners:

   /**
    * @see \Illuminate\Auth\Events\Registered
    */
   public function handle(Registered $event)
   

Advanced Patterns

• Dynamic Templates: Use Twig’s {% extends %} to create reusable layouts (e.g., base.md.twig for shared headers/footers).
• Custom Macros: Extend functionality by adding Twig macros in templates/markdown/macros.twig:

  {# templates/markdown/macros.twig #}
  {% macro laravel_note(content) %}
      > **Laravel Note**: {{ content }}
  {% endmacro %}
  

  Use in templates:

  {{ _self.laravel_note('Use Facades for external services.') }}
  

Gotchas and Tips

Pitfalls

1. GitHub Wiki Limitations:

   • Issue: Links to nested .md files (e.g., classes/YourClass.md) break in GitHub wikis.
   • Fix: Use GitLab wikis or flatten the structure (e.g., YourClass.md in root).

2. PHPDoc Parsing Quirks:

   • Issue: Undocumented @param types or missing @return may cause malformed tables.
   • Fix: Ensure consistent PHPDoc syntax:

     // Good
     /**
      * @param string $name [Description]
      * @return int
      */
     

     // Bad (avoid)
     /**
      * @param $name
      */
     

3. Template Caching:

   • Issue: phpdoc caches templates; changes may not reflect until cache is cleared.
   • Fix: Use --cache=none or delete phpdoc.cache/ manually.

4. Twig Escaping:

   • Issue: Special characters (e.g., |, _) in docblocks may break Markdown.
   • Fix: Escape manually in Twig:

     {{ docblock|replace({'|': '\|', '_': '\_'}) }}
     

Debugging

1. Verify PHPDoc Parsing: Run with --parse-only to check if PHPDoc reads your annotations:

   phpdoc --directory=src --parse-only
   

   Look for warnings in output.

2. Inspect Generated Markdown:

   • Use phpdoc --template="vendor/saggre/phpdocumentor-markdown/themes/markdown" --debug to see Twig rendering steps.
   • Validate Markdown with Markdown Lint.

3. Template Debugging:

   • Enable Twig debugging in templates/markdown/config.twig:

     {# config.twig #}
     {% set debug = true %}
     

   • Check docs/_debug/ for rendered Twig variables.

Configuration Quirks

1. File Extensions in URLs:

   • Default: Template omits .md from links (e.g., [Class](classes/YourClass)).
   • Override: Set use_file_extensions in phpdoc.dist.xml:

     <phpdocumentor>
         <template name="templates/markdown" use_file_extensions="true"/>
     </phpdocumentor>
     

2. Table of Contents:

   • Issue: TOC may include private methods.
   • Fix: Filter in toc.md.twig:

     {% for method in element.methods %}
         {% if method.access !== 'private' %}
             - [{{ method.name }}](#{{ method.name }})
         {% endif %}
     {% endfor %}
     

3. Custom Directories:

   • Issue: Docs generate in docs/ but you want api-docs/.
   • Fix: Use --target:

     phpdoc --directory=src --target=api-docs --template="..."
     

Extension Points

1. Add Custom Sections:

   • Extend class.md.twig to include Laravel-specific sections (e.g., migrations, policies):

     {# templates/markdown/class.md.twig #}
     ## Policies
     {% if element.policies|length > 0 %}
         {% for policy in element.policies %}
             - [{{ policy }}]({{ policy }}.md)
         {% endfor %}
     {% endif %}
     

2. Post-Processing:

   • Use a script to transform generated Markdown (e.g., add GitHub badges):

     find docs -name "*.md" -exec sed -i '/^# /a \n![CI](https://github.com/.../actions/workflows/ci.yml/badge.svg)'