README

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")

csoellinger / dog-html-printer

Maintainers

Details