batboat/documentor

Samler og genererer dokumentation fra PHP-filer via artisan-kommando

dev-master 2025-06-29 20:31 UTC

Requires

• php: ^8.1
• batboat/tools_laravel: ^1.0
• symfony/yaml: ^6.0 || ^7.0

MIT

• batboat

README

En simpel Laravel-pakke til automatisk at samle og generere dokumentation fra dine PHP-filer via en Artisan-kommando.

Hvad kan den?

• Scanner ét eller flere biblioteker/projekter efter PHP-filer og ekstrakterer deres fulde kildekode.
• Ekskluderer automatisk mapper som .git (og andre “typer” du definerer) ved hjælp af en fleksibel type-baseret filtermekanisme.
• Understøtter flere profiler i samme konfiguration (f.eks. én profil pr. pakke eller gruppe af filer).
• Genererer output i valgfri formater (TXT, MD osv.) inkl. en valgfri indholdsfortegnelse over alle fundne filer.
• Debug-mode giver detaljeret indsigt i, hvilke filer og mapper der scannes og ekskluderes.

Installation

1. Tilføj pakken via Composer:

   composer require batboat/documentor

2. (Valgfrit) Publicér konfigurationsfilen, hvis du vil tilpasse indstillingerne:

   php artisan vendor:publish --provider="Batboat\Documentor\DocumentorServiceProvider" --tag=config

3. Rediger config/batboat/documentor.yml efter dine behov.

Konfiguration (config/batboat/documentor.yml)

basic:
  # Mappenavn under storage_path() hvor dokumentationsfiler gemmes
  path: documentor

  # Aktiver debug-udskrifter i konsollen
  debug: true

  # Globale exclude-typer: hver type håndteres via ExcludeTypeProcessor
  exclude:
    types:
      git: true   # true/false; udelukker alle .git-mapper

profiles:  # Dokumentations-profiler
  package_batboat_documentor:
    include:
      - packages/batboat/documentor   # Mapper/filer der skal dokumenteres
    exclude: []                      # Specifikke stier der skal udelukkes (ud over typer)
    output:
      - txt                          # Output-format(er): txt, md osv.
    options:
      files_index: true              # Medtag en oversigt over alle fundne filer

  package_batboat_artisan-menu-collector:
    include:
      - packages/batboat/artisan-menu-collector
    exclude: []
    output:
      - txt
    options:
      files_index: true

  package_batboat_all:
    include:
      - packages/batboat/artisan-menu-collector
      - packages/batboat/documentor
    exclude: []
    output:
      - txt
    options:
      files_index: true

Forklaring af sektioner

• basic.path Angiver hvor de genererede dokumentationsfiler gemmes (under Laravel storage_path()).

• basic.debug Når true, aktiveres detaljeret debug-udskrift, så du kan se præcis, hvad der scannes og ekskluderes.

• basic.exclude.types En liste af typer—hvert nøglenavn svarer til en handle<Type>Type-metode i ExcludeTypeProcessor. F.eks. git: true udelukker .git.

• profiles Undersektion for hver dokumentationsprofil:

  • include: Array af fil- eller mappestier, der skal scannes.
  • exclude: Liste af specifikke stier (relativt til projektrod) der skal udelukkes ud over dem, der defineres på typeniveau.
  • output: Hvilke filformater (f.eks. txt, md) der skal genereres.
  • options.files_index: Hvis true, indsætter en oversigt over alle scannede filer i toppen af dokumentationen.

Brug

Kør kommandoen:

php artisan documentor

Resultatet gemmes som <profilnavn>.<ext> i den mappe, du har angivet under basic.path.

Intern struktur

• Commands/GenerateDocumentationCommand.php Hovedkommandoen, som læser konfiguration, scanner filer ved hjælp af en RecursiveCallbackFilterIterator og genererer output.

• Excludes/ExcludeTypeProcessor.php Indeholder logik til at tilføje type-baserede eksklusioner (f.eks. .git).

• DocumentorServiceProvider.php Loader YAML-konfiguration og registrerer Artisan-kommandoen.

• config/batboat/documentor.yml Din hovedkonfigurationsfil med profiler og globale indstillinger.

• config/batboat/example.yml Eksempelfil til inspiration med ekstra profiler og formater.

Tips og udvidelser

• Tilføj flere typer i ExcludeTypeProcessor (fx node_modules, vendor).
• Understøt HTML-, JSON- eller PDF-output ved at udvide output-logikken.
• Integrer i din CI/CD-pipeline for automatisk generering af dokumentation på hver build.

Med Batboat Documentor får du et hurtigt overblik over din PHP-kildekode i ren tekst eller markdown—ideelt til intern dokumentation og kodegennem