README

👁 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