Docudoodle Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require genericmilk/docudoodle
   php artisan vendor:publish --tag=docudoodle-config
   

   Publish the config file to customize settings in config/docudoodle.php.

2. Configure API Key: Add your OpenAI (or alternative provider) key to .env:

   OPENAI_API_KEY=sk-your-key-here
   DOCUDOODLE_API_PROVIDER=openai  # or 'claude', 'gemini', 'azure', 'ollama'
   

3. First Run:

   php artisan docudoodle:generate
   

   Outputs Markdown files to storage/docudoodle (configurable).

First Use Case

Document a Legacy Laravel App:

php artisan docudoodle:generate --skip-dirs="vendor/,node_modules/,tests/"

• Skips unnecessary directories.
• Generates Markdown for all PHP files in app/, config/, and routes/.
• Ideal for onboarding new developers or auditing existing code.

Implementation Patterns

Daily Workflows

1. Post-Feature Documentation:

   php artisan docudoodle:generate --force-rebuild
   

   • Forces regeneration of all files after implementing a new feature.
   • Overrides cache to ensure updated docs reflect changes.

2. Incremental Updates:

   php artisan docudoodle:generate --no-cache
   

   • Skips cached files, reprocessing only modified files.
   • Reduces API costs and runtime for frequent updates.

3. Team Onboarding:

   php artisan docudoodle:generate --output-dir=docs/onboarding
   

   • Generates docs in a dedicated directory for new hires.
   • Combine with --jira or --confluence for centralized access.

Integration Tips

• CI/CD Pipeline: Add to phpunit.xml or GitHub Actions:

  <php>
      <env name="OPENAI_API_KEY" value="${{ secrets.OPENAI_API_KEY }}" />
  </php>
  

  Run as a post-commit hook or scheduled job.

• Laravel Events: Trigger docs generation after ModelCreated or MigrationRan:

  use GenericMilk\Docudoodle\Facades\Docudoodle;
  
  event(new ModelCreated(User::class));
  Docudoodle::generate(['app/Models/User.php']);
  

• Custom Prompts: Extend the default template (resources/docudoodle/templates/default.md) to include:

  ## Security Notes
  {# if contains(FILE_CONTENT, 'password') #}
  - **Sensitive Data**: Ensure encryption is applied to `{BASE_NAME}` fields.
  {/if #}
  

Gotchas and Tips

Pitfalls

1. API Rate Limits:

   • Symptom: 429 Too Many Requests errors.
   • Fix: Adjust max_tokens in config/docudoodle.php or use --no-cache to batch requests.
   • Tip: Monitor usage with DOCUDOODLE_DEBUG=true in .env.

2. Wildcard Skip Directories:

   • Issue: skip_dirs with * (e.g., tests/*/) may not work as expected.
   • Workaround: Use absolute paths or regex patterns in DocudoodleServiceProvider.

3. Ollama Offline Mode:

   • Problem: Docs may fail if Ollama isn’t running.
   • Solution: Add a health check:

     if (!Docudoodle::isOllamaRunning()) {
         throw new \RuntimeException('Ollama service unavailable. Docs skipped.');
     }
     

Debugging

• Cache Issues:

  • Delete .docudoodle_cache.json to force a full rebuild.
  • Verify cache_file_path is writable:

    chmod 666 storage/docudoodle/.docudoodle_cache.json
    

• Template Errors:

  • Validate custom templates with:

    php artisan docudoodle:generate --debug
    

  • Check for unclosed {# #} blocks or invalid variables.

Extension Points

1. Custom Output Formats: Override GenericMilk\Docudoodle\Services\MarkdownRenderer to generate HTML/PDF:

   class HtmlRenderer extends MarkdownRenderer {
       protected function renderContent(string $content): string {
           return (new \ParsedownExtra())->text($content);
       }
   }
   

2. Pre/Post-Processing: Hook into the docudoodle.generated event:

   Docudoodle::generate(['app/Http/Controllers/*.php']);
   event(new \GenericMilk\Docudoodle\Events\DocumentationGenerated(
       'app/Http/Controllers/',
       'storage/docudoodle/controllers'
   ));
   

3. Azure OpenAI:

   • Tip: Use DOCUDOODLE_AZURE_EMBEDDINGS=true for vector search integration.
   • Quirk: Ensure azure_api_version matches your deployment’s API version.

Performance Tips

• Batch Processing: Limit concurrent API calls with:

  'concurrency_limit' => 3, // in config/docudoodle.php
  

• Exclude Large Files: Add to skip_dirs:

  'skip_dirs' => [
      'vendor/*',
      'database/migrations/*', // Often verbose
  ],
  

• Local Caching: Use DOCUDOODLE_CACHE_DRIVER=file for faster reprocessing.

Laravel-Specific Quirks

• Service Provider Binding: If using Laravel’s service container, bind the Docudoodle facade:

  $this->app->bind('docudoodle', function ($app) {
      return new \GenericMilk\Docudoodle\Docudoodle(
          $app['config']['docudoodle']
      );
  });
  

• Artisan Command Conflicts: Avoid naming custom commands docudoodle:generate to prevent conflicts.

• File System Permissions: Ensure storage/docudoodle is writable:

  mkdir -p storage/docudoodle && chmod -R 775 storage/docudoodle