datashaman/lowdown

Documentation generator for PHP projects

0.1.0 2019-05-13 05:58 UTC

This package is auto-updated.

Last update: 2024-11-14 04:18:43 UTC


README

Lowdown will generate documentation with as much detail as you provide in the form of type hints and PHPDoc annotations or docblocks within your project.

All docblocks are run through a Markdown parser.

Lowdown pays special attention to functions and methods which include a <pre></pre> block in the docblock.

Whatever is within the <pre></pre> tag is deemed to be a code example.

The example is extracted and evaluated dynamically; the output is saved for inclusion in the documentation.

To further sweeten the deal, the example code can be posted to GitHub as a gist.

A link to run it as a Melody script is generated with the documentation.

install

Install the composer package into your project as a dev dependency:

composer require --dev datashaman/lowdown

configure

Add environment variables to your .env to configure the build process. These are all optional.

  • LOWDOWN_DEST The destination folder where documentation is written to. Defaults to docs/api.
  • LOWDOWN_GISTS_CACHED GitHub Gist requests should be cached. Defaults to true.
  • LOWDOWN_GISTS_TOKEN GitHub personal access token. Used for generating Gists.
  • LOWDOWN_GISTS_USERNAME GitHub username. Used for generating Gists.
  • LOWDOWN_SOURCES The source folders where documentation is generated from. Comma-delimited. Defaults to app,src.
  • LOWDOWN_WHITELIST Namespace whitelist. If set, documentation will be generated for only these namespaces. Comma-delimited.

build

Build your package's documentation:

lowdown build

Build your package's documentation with Gists included:

lowdown build --gist

serve

Serve your package's documentation:

lowdown serve