Skip to content

logo Dog

Build Status Test Coverage Maintainability Packagist

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