Skip to content

klitsche/dog

Folders and files

NameName
Last commit message
Last commit date

Latest commit

e35e2c8 · Nov 29, 2020

History

75 Commits
Nov 23, 2020
Nov 24, 2020
Nov 21, 2020
Nov 29, 2020
Nov 23, 2020
Nov 23, 2020
Jul 12, 2020
Nov 26, 2020
Feb 24, 2020
Nov 26, 2020
Nov 26, 2020
Nov 26, 2020
Nov 22, 2020
Nov 20, 2020
Nov 18, 2020
Nov 21, 2020
Nov 20, 2020

Repository files navigation

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 ^7.4

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 travis
  • Add cmd interface for dog bin
  • Add validation rules
  • Add documentation (mkdocs, github page)
  • Add tests
  • Add support for printer config - eg. templatePath
  • Improve description printing - (inheritDoc, inline tags, ...)
  • Add direct element interface for proposed PSR-19 tags
  • Add phar / phive packaging