PHPDoc-VuePress

# Getting started

# Requirements

  • PHP >= 5.6 (PHP < 8.0 for your code, PHP 7.2 recommended for building documentation)
  • Node.js >= 8 < 18
  • Yarn (opens new window) (or npm).

# Dependencies

You can globally install them:

# phpDocumentor2 globally
composer global require phpdocumentor/phpdocumentor:^2.9.1

# VuePress
npm i -D vuepress

Read about VuePress install (opens new window).

phpDocumentor3 compatibility

At the moment, this template is not compatible with the stable release of phpDocumentor 3, which supports new features of the latest PHP versions.

It should generate documentation of any code written on PHP < 8, but, as phpDocumentor 2, the documentation should be generated on PHP 7.2 or 7.3. You can configure a CI like Travis CI, Netlify of Github Actions to generate the API documentation on PHP 7.2 for your code if not using it on your local environment.

Compatibility with phpDocumentor 3 is in progress 🚧 to support new features it offers.

# Installation

Install nelson6e65/phpdoc-vuepress with composer:

composer require --dev nelson6e65/phpdoc-vuepress

Pre-releases: You may need to set the composer option minimum-stability (opens new window) to 'dev' in order to be able to install pre-releases.

# Usage

First, you need to prepare your project to use phpDocumentor and VuePress to generate your API documentation.

After that, using that configuration you only need to generate the markdown pages from your code with phpDocumentor and then build your VuePress documentation:

$ phpdoc # This will use the `phpdoc.dist.xml` config file

$ vuepress build docs # Where `docs/` is the directory you configured

Done! Your API documentation is live!

TIP

If you already have a default VuePress configuration and you want just quickly run phpDocumentor, you can use:

phpdoc -d="src/" -t="docs/api/" --template="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress"

This assumes:

  • PHP sources are in: src/,
  • VuePress documentation is located in docs/,
  • VuePress will use /api route for the API documentation and sidebar is (/will be) configured with the files generated by phpDocumentor.

Please, check the Configuration page for examples and guides instead.

# Recommendations

  • Do not track the API route directory with Git. This files are auto-generated with the phpdoc tool, so there is not need to track them. Add to your .gitignore:
# Autogenerated API documentation
docs/api/
  • Restrict visibility to protected members. By default, all members are parsed. So, you need to config --visibility to ignore private methods:
phpdoc --visibility="public,protected"

or

<parser>
  <!-- Only Public and Protected members are parsed -->
  <visibility>public,protected</visibility>
</parser>

← Configuration →