Documentor Bundle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require-dev artur-gajewski/documentor-bundle
   

   Add to AppKernel.php under dev/test environment:

   $bundles[] = new Aga\DocumentorBundle\DocumentorBundle();
   

2. First Run:

   php app/console documentation:create
   

   Access generated docs at:

   http://yourproject.dev/app_dev.php/bundles/documentor/index.html
   

3. Key Files:

   • app/console (for CLI commands)
   • web/bundles/documentor/ (output directory)
   • src/ (default source directory, configurable)

Implementation Patterns

Workflows

1. Development Workflow:

   • Run documentation:create after code changes:

     php app/console documentation:create --force  # Overwrite existing docs
     

   • Access docs via browser during sprints for quick reference.

2. CI/CD Integration:

   • Trigger docs generation in CI (e.g., GitHub Actions) for pre-release builds:

     - name: Generate Docs
       run: php app/console documentation:create
     

   • Store generated docs in web/bundles/documentor/ for artifact uploads.

3. Custom Source Paths:

   • Override default src/ path via config (config.yml):

     aga_documentor:
         source_dirs: ['src', 'lib']
     

Integration Tips

• Symfony Assets: Bundle auto-runs assets:install post-generation. Disable if using custom asset workflows:

  php app/console documentation:create --no-assets
  

• phpDocumentor2 Customization: Pass CLI args directly to phpdoc via --phpdoc-args:

  php app/console documentation:create --phpdoc-args="--template=responsive"
  

• Environment Isolation: Ensure bundle is only enabled in dev/test to avoid bloating production.

Gotchas and Tips

Pitfalls

1. Permission Issues:

   • web/bundles/documentor/ must be writable by the web server (e.g., chmod -R 775 web/bundles/).
   • Fix: Run assets:install manually if docs fail to copy:

     php app/console assets:install --symlink
     

2. phpDocumentor2 Dependencies:

   • Bundle assumes phpdoc is globally available. If missing:

     composer global require phpdocumentor/phpdocumentor2
     

   • Alternative: Use local install via --phpdoc-path:

     php app/console documentation:create --phpdoc-path=./vendor/bin/phpdoc
     

3. Caching Quirks:

   • Generated docs may not reflect real-time changes due to caching. Use --force to bypass:

     php app/console documentation:create --force
     

Debugging

• Verbose Output: Enable debug mode for command details:

  php app/console documentation:create -vvv
  

• Log File: Check app/logs/dev.log for phpDocumentor2 errors (e.g., missing @property tags).

Extension Points

1. Custom Templates: Override default template by extending phpDocumentor2's config:

   aga_documentor:
       phpdoc_config:
           templates:
               - responsive
   

2. Post-Generation Hooks: Use Symfony’s event system to run tasks after docs generate. Example in DocumentorBundle:

   // services.yml
   services:
       my.post_doc_hook:
           class: AppBundle\Service\PostDocHook
           tags:
               - { name: kernel.event_listener, event: documentor.post_generate, method: onPostGenerate }
   

3. Excluding Directories: Filter out non-documented paths via config:

   aga_documentor:
       source_dirs:
           - { path: src, exclude: ['Tests', 'Entity/Listener'] }
   

```markdown
### Pro Tips
- **Symlink Docs**:
  For local development, symlink `web/bundles/documentor` to a global `~/docs` folder for quick access across projects:
  ```bash
  ln -sf ~/projects/myapp/web/bundles/documentor ~/docs/myapp

• Versioned Docs: Append a hash to the output path (e.g., web/bundles/documentor/v1.0) to support multiple versions:

  aga_documentor:
      target_dir: "%kernel.root_dir%/../web/bundles/documentor/v{{ app.version }}"
  

• Parallel Generation: Speed up large projects by leveraging phpdoc's parallel processing:

  php app/console documentation:create --phpdoc-args="--processes=4"