klitsche/dog

Source code documentation generator for PHP libraries

v0.5.0 2023-01-21 23:37 UTC

Requires

• php: ^8.0
• phpdocumentor/reflection: ^4.0 || ^5.0
• symfony/console: ^5.0 || ^6.0
• symfony/event-dispatcher: ^5.0 || ^6.0
• symfony/filesystem: ^5.0 || ^6.0
• symfony/finder: ^5.0 || ^6.0
• symfony/stopwatch: ^5.0 || ^6.0
• symfony/yaml: ^5.0 || ^6.0
• twig/twig: ^3.0

Requires (Dev)

• humbug/box: 4.2.0
• phpunit/phpunit: ^9.4
• symplify/easy-coding-standard: ^10.3

Suggests

• ext-json: To use enricher PHPLOC
• ext-simplexml: To use enricher Clover

MIT

• Dirk Adler

• generator
• documentation
• phpdoc
• twig
• api
• markdown
• source code

README

Dog is a slim source code documentation generator for PHP libraries. It´s a thin layer around phpdocumentor/reflection and twig.

WIP: Expect breaking changes along all 0.* pre-releases.

Features

• Easily generates source code documentation
• Looks into code and phpdoc
• Helps to optimize code and phpdoc for documentation with customizable rules (based on proposed PSR-19)
• Outputs markdown (e.g. for use with mkdocs-material)
• Analyzes source code PHP ^5.2
• Provides support for custom printer logic & easy templating (planned)
• Provides support for custom enricher logic to add relevant & related data

Runtime Requirements

• PHP ^8.0

Suggested:

• json extension to enrich phploc data
• simplexml extension to enrich clover coverage data

Quick Start

Add to your project:

composer require --dev klitsche/dog

Create config file .dog.yml in your project root directory and edit it.

Example:

# Title of index page
title: 'Overview'
# Relative or absolute paths to source files - plus patterns to include or exclude path pr files
srcPaths:
  'src':
    '/.*\.php$/': true
# Add new or change validation rules - omit completely to use default set
rules:
  PublicFileDocBlockMissingRule:
    class: 'Klitsche\Dog\Analyzer\Rules\DocBlockMissingRule'
    issueLevel: 'ignore'
    match:
      getElementType: 'File'
# Configure enrichers to add extra data to project or element items
enrichers:
  clover:
    class: \Klitsche\Dog\Enrichers\Clover\CloverEnricher
    file: clover.xml
# FQCN for template printer class
printerClass: 'Klitsche\Dog\Printer\Markdown\Printer'
# Relative or absolute path to output directory
outputDir: 'docs/api'
# Enable or disable debug mode - helps when tweaking templates
debug: false

Analyze code and phpdoc first, then generate documentation:

vendor/bin/dog

Analyze code & phpdoc and find potential documentation issues without generating documentation:

vendor/bin/dog --analyze

Generate documentation without analyzing it first:

vendor/bin/dog --generate

Documentation

https://klitsche.github.io/dog/

Todos

• Add code style checks
• Add GitHub actions
• Add cmd interface for dog bin
• Add validation rules
• Add documentation (mkdocs, github page)
• Add tests
• Add support for printer config - eg. templatePath
• Add phar packaging
• Improve description printing - (inheritDoc, inline tags, ...)
• Add direct element interface for proposed PSR-19 tags
• Add phive packaging