PHPDoc-VuePress

# Configuration

# Configuring phpDocumentor

These instructions are for phpDocumentor 2. phpDocumentor 3 is not yet compatible.

You need to tell phpDocumentor (1) where are your PHP source files, (2) where to generate the API documentation and (3) where is the template (for a Composer project, is ). You can, also, (4) configure which elements include by its visibility.

In order to accomplish this, you must create a configuration file named phpdoc.dist.xml and setup (1, 2, and 3).

Template location [3]

If you installed via Composer, the template will be located at vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress directory.

<transformations>
  <template name="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" />
</transformations>

You can use the configuration of this project as example and guide. Just edit the values that suits your project.

# Example

Here is the explained phpDocumentor configuration for this project:

<?xml version="1.0" encoding="UTF-8" ?>
<phpdoc>
  <!-- Title of your project. It will be used to show a mini description -->
  <title>`phpdoc-vuepress` demo</title>

  <!-- [1]
  Directories and files from where will be extracted the documentation;
  where your PHP sources are. -->
  <files>
    <!-- In this case, the soures to document are in the `demo/` dir-->
    <directory>demo</directory>
    <!-- You can include as many <directory> you need. And also, specific files
    by using <file> tag-->
    <!-- <file>vendor/cakephp/utility/Text.php</file> -->
  </files>

  <transformer>
    <!-- [2]
    Directory where the generate documentation files be. Set it according to
    your VuePress config. In this case, it will be used the route `/demo`,
    but you can use any you want -->
    <target>docs/demo</target>
  </transformer>

  <transformations>
    <!-- [3] Directory where the template.xml is. In this case, the template.xml file is in that directory -->
    <template name="data/templates/vuepress" />
    <!-- But in your Composer project, you should use the following line instead of the previous one. -->
    <!-- <template name="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" /> -->
  </transformations>

  <parser>
    <!-- [4] Elements to include in your documentation by visibility:
         public, protected and private. -->
    <visibility>public,protected</visibility>

    <!-- Directory where to put the cache. This can be set to any directory.
         Remember ignore it by Git -->
    <target>build/api-cache</target>
  </parser>
</phpdoc>

Then, you can just run phpdoc.

For further information, check the Configuring phpDocumentor page (opens new window).

# Configuring VuePress

If you don't already have configured your VuePress, you can follow the setup instructions (opens new window).

Depending on version you are using, the docs/.vuepress/config.js file you created should following the Config Reference according to v0.x (opens new window) or v1.x (opens new window).

Once done, you only need to include the files generated by phpDocumentor in your sidebar as you like.

This template generates this files:

  • README.md: Introduction to your API documentation. [extra]
  • classes.md: Documentation of your classes.
  • interfaces.md: Documentation of your interfaces.
  • traits.md: Documentation of your traits.
  • functions.md: Documentation of your global/namespaced functions.
  • constants.md: Documentation of your global/namespaced constants.

# Example

Here is the explained VuePress configuration for this project. Use it as example and guide:

module.exports = {
  // Directory where will be generated the HTML files by VuePress
  dest: 'dist/phpdoc-vuepress/',

  // Base URL. Useful for GitHub pages.
  base: '/',

  // Title of your project
  title: 'PHPDoc-VuePress',

  // Description of your project
  description: 'Template for generating your PHP API documentation in a pretty VuePress format',

  head: [
    ['link', { rel: 'icon', href: '/favicon.svg' }], // Custom favicon
  ],

  // Plugins config
  plugins: {
    '@vuepress/google-analytics': {
      ga: 'UA-58599811-1', // GoogleAnalytics ID (optional. use your own ga)
    },
    '@vuepress/back-to-top': {},
  },

  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' }, // Link to a non-api-documentation section
      { text: 'API (demo)', link: '/demo/' }, // Lint to our API documentation route
    ],

    sidebar: {
      '/guide/': [
        // Normal documentation sidebar
        {
          title: 'Guide',
          collapsable: false,
          children: [
            // Normal pages
            '',
            'getting-started',
            'configuration',
          ],
        },
      ],

      // Your API documentation sidebar
      // Here is where will be generated your files (`docs/demo/` in this case).
      // This is the directory you configured in your `phpdoc.dist.xml` as target
      // directory (or `-t` option of phpdoc)
      '/demo/': [
        {
          title: 'API Demo',
          collapsable: false,
          children: [
            //
            '', // Ref. to the `README.md` file
            'classes', // Ref. to the `classes.md` file
            'interfaces', // Ref. to the `interfaces.md` file
            'traits', // Ref. to the `traits.md` file
            'functions', // Ref. to the `functions.md` file
            'constants', // Ref. to the `constants.md` file
          ],
        },
      ],
      '/': [''],
    },

    // You can ignore the following optional customizations --------------------

    markdown: {
      lineNumbers: false,
      toc: { includeLevel: [1, 2, 3] },
    },

    sidebarDepth: 3,

    lastUpdated: true,

    evergreen: true,

    // Repository configurations
    repo: 'nelson6e65/phpdoc-vuepress',
    docsDir: 'docs',
    editLinks: true,
  },

  // custom webpack configuration
  configureWebpack: {
    resolve: {
      alias: {
        // Aliases
        '@github': '../../.github/assets',
      },
    },
  },
};

Then, you can just run vuepress build docs.

TIP

If you installed VuePress as project dependency, you can configure scripts in your package.json:

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

And then just run npm run docs:build 😎.

Read about recommended directory structure at https://vuepress.vuejs.org/guide/directory-structure.html (opens new window)

WARNING

You can use any directory as the target for your API, but you need to use the same route level for them in order link references work. For example, all under '/demo/' as the above example.

# Extras

# Running phpDocumentor without a configuration file

Is not recommended, but for small projects (not using many directories), you can build your documentation without a configuration file by passing the arguments to the phpdoc command directly.

For example, if your code is under demo/ directory and your VuePress resides in docs/, and your route /api/, you may use:

$ phpdoc -d demo/ -t docs/api/ --template=vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress

WARNING

The target directory (-t) will be used by phpDocumentor as cache too, so there will be some extra files populating your documentation directory. In order to avoid this, use the --cache-folder option.

TIP

You can add the command as Composer script:

"scripts": {
    "phpdoc": [
        "phpdoc -d demo/ -t docs/api/ --template=vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress --ansi"
    ]
},

And then just run composer phpdoc 😎.

For further information, check the Runing phpDocumentor documentation (opens new window).

←