csoellinger/dog-html-printer

HTML printer for Dog, a simple code documentation generator.

• About
• Installation
• Usage
• Documentation / Demo
• Contributing
  • Known Issues
  • ToDo
• Copyright and License

About

A HTML printer for Dog PHP Documentation Generator. It is heavily inspired by Doctum, phpDox and other good projects. The printer is Work-In-Progress at the moment but it is already very configurable and has a nice look with many features like: Tree Navigation, Source Code implementation, PhpLoc overview, readme renderer and some more are planned. Take a look at the todo section.

Installation

First: You need to install Dog PHP Documentation Generator.

Second: For now you have to allow minimum stability dev inside composer file cause the latest version of highlight.php works like a charm but isn't released yet, so we use the dev-master branch.

Add this to your composer.json file:

{
    "minimum-stability": "dev",
    "prefer-stable" : true,
}

At least install the html printer:

composer require --dev csoellinger/dog-html-printer

Usage

After you have installed Dog and Dog HTML printer you can customize your .dog.yml to use the new printer class.

# Most configurations are by the dog package itself.

# Title
title: 'Dog HTML printer'

# Relative or absolute paths to source files - plus patterns to include or exclude path pr files
srcPaths:
  'src':
    '/.*\.php$/': true

# Configure enrichers to add extra data to project or element items
# phploc is supported by DogHtmlPrinter
enrichers:
    phploc:
        class: Klitsche\Dog\Enrichers\PHPLOC\PHPLOCEnricher
        file: phploc.json

# Set the printer class to DogHtmlPrinter
printerClass: 'CSoellinger\DogHtmlPrinter\HtmlPrinter'

# Printer configuration
printerConfig:
    # Set a custom template path. If you want do this, best way would be to copy the resources/templates dir
    # from this package to you project dir and then customize the templates.
    # templatesPath: 'resources/templates'

    # If you want add a readme file
    readme: 'README.md'

    # Include source code
    includeSource: true

    # Ignore code marked as @internal
    ignoreInternal: true

    # Ignore private things (methods, properties,...)
    ignorePrivate: true

    # Minify CSS and JS at output
    minifyCssAndJs: true

    # Minify HTML at output. Slows down the build!!
    minifyHtml: false

# Relative or absolute path to output directory
outputDir: 'docs/html'

# Optional cache dir
cacheDir: 'build/cache'

# Enable or disable debug mode - helps when tweaking templates
debug: false

Right after customizing the configuration you can start building your documentation.

vendor/bin/dog

Documentation / Demo

https://csoellinger.github.io/dog-html-printer

Contributing

Contributions are welcome! To contribute, please familiarize yourself with CONTRIBUTING.md.

If you found a bug or have an idea feel free to post it here on github.

Known Issues

• Linking inside readme to other markdown files causes problems
• Collapse tree navigation also selects item

ToDo

• Generate local static search
• Include coverage data to printer output
• Include testing data to printer output
• Project testing
• Mobile optimization
• Replace or customize bootstrap with only needed stuff
• Sub-Dir layout config instead of flat dir output.
• Optimize
  • Strip bootstrap down to only needed components
  • Some code parts are a bit "hacky"
• Theming
  • Append custom css via printer config
  • Theming system to use a new theme without writing a new printer class (like "custom templates path")

Copyright and License

The csoellinger/dog-html-printer library is copyright © Christopher Söllinger and licensed for use under the terms of the MIT License (MIT). Please see LICENSE for more information.