nelson6e65 / phpdoc-vuepress

🎨 Template for generating your PHP API documentation in a pretty VuePress format

PHPDoc-VuePress

Template for generating your PHP API documentation in a pretty VuePress format.

This package provides a phpDocumentor 2 template to generate the API documentation of your code to be integrated in a nice looking VuePress project.

WIP: 🚧🏗 Compatibility with phpDocumentor 3 in progress.

Features

This template will generate six VuePress *.md files with the DocBlock documentation in your target directory:

• README.md: Entry point of your API Documentation. Contains, at the moment, an introduction and references to blocks used in the site.
• classes.md: Contains all classes, sorted by namespace.
• interfaces.md: Contains all interfaces, sorted by namespace.
• traits.md: Contains all traits, sorted by namespace.
• constants.md: Contains all global constants, sorted by namespace.
• functions.md: Contains all global functions, sorted by namespace.

Demo

Check a demo of documentation generated with this template in https://phpdoc-vuepress.netlify.app/demo

Explore sources of nelson6e65/phpdoc-vuepress to use configuration files as guide.

A real project API generated using this template: nelson6e65/php_nml.

Requirements

• PHP >= 5.6 < 8.0
• Node.js >= 8 < 18
• phpDocumentor 2.
• Yarn (or npm)
• VuePress.

This template is designed for phpDocumentor 2 and VuePress 1. Read more about dependencies in the Documentation.

Note: phpDocumentor 2 is able to generate documentation of code written on maybe any version of PHP < 8, but should be run on PHP 7.2. You can configure a CI like Travis CI, Netlify of Github Actions to generate the 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

Note for pre-releases: You may need to set the composer option minimum-stability to 'dev' or 'beta' in order to be able to install pre-releases.

Usage

Run phpDocumentor and set template as vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress:

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

More information about the available arguments can be found at running phpDocumentor.

Configuration

See the Configuration section in the documentation for setup examples.

Further reading

Check the documentation for more information https://nelson6e65.github.io/phpdoc-vuepress/.

Contributing

Check out the CONTRIBUTING.md file for details about contributing.

License

Copyright (c) 2018-2023 Nelson Martell

Read the LICENSE file for details.

Note: This template is based on Markdown template created by @cvuorinen: cvuorinen/phpdoc-markdown-public.

phpdoc-vuepress's Issues

[feature] Export a Default VuePress app skeleton

Scopes

• Installation
• Other

Is your feature request related to a problem? Please describe.
What if I want only to document the API and have not another documentation? Or what if I already wrote the non-api-documentation using another tool?

Describe the solution you'd like

• Export a basic preconfigured VuePress app skeleton.

Describe alternatives you've considered
Create another package for creating the VuePress app skeleton for this feature.

[feature] Include overview sections

Scopes

• Output HTML
• Output Markdown

Describe the solution you'd like

• Include a general overview as the main page and move help description to an optional page.
• Include an overview section in each API page (classes.md, etc), containing an index of elements.
• Include an overview section of each structure (class, interface, trait) containing a list/table of its members.

[feature] Implement custom-links

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Output HTML
• Output Markdown
• Appearance
• Other

Is your feature request related to a problem? Please describe.
Difficult to add custom internal links between elements (class/members/etc).

Describe the solution you'd like
Add normalized links, so accessible by expected links.

Describe alternatives you've considered
A clear and concise description of any alternative solutions or features you've considered.

Additional context

• https://github.com/abernov/markdown-it-custom-header-link
• vuejs/vuepress#679 (comment)

Normalize documentation deployment

File not found at path: vuepress/.assets

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Output HTML
• Output Markdown
• Appearance
• Other

Describe the bug

Parsing files

Applying transformations (can take a while)
21:22:43 ERROR     [console] Error thrown while running command "-d="src/" -t="docs/php/" --template="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress". Message: "File not found at path: vuepress/.assets" ["exception" => League\Flysystem\FileNotFoundException^ { …},"command" => "-d="src/" -t="docs/php/" --template="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress"","message" => "File not found at path: vuepress/.assets"]

In Filesystem.php line 389:

  File not found at path: vuepress/.assets  

Steps to reproduce

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

Invalid handle of inline @see tag

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Appearance
• Other

Describe the bug
Inline @see generates a link to an undefined HTML file.

Steps to reproduce
Steps to reproduce the behavior:

1. Add an inline reference to a class with @see tag (e.g. {@see Example}) in a DocBlock
2. Generate documentation
3. See the .md file generates a link like [\NelsonMartell\VuePress\Demo\Example](../classes/NelsonMartell.VuePress.Demo.Example.html)

Expected behavior
It should generate a propper link to the class, trait or interface, same as other link references: [Namespace\\\<span style="font-weight: bold;">Class</span>](classes.html#namespace-class)

Enviroment:

• OS: [e.g. Fedora 29, Windows 7, etc]
• Browser: [e.g. chrome, safari]

Versions:

• Template: v1.0.0-beta.3
• PHP: 7.2
• Node: v8.11.2
• Yarn: 1.13.0
• VuePress: 0.14.8 | 1.0.0-alpha.32
• phpDocumentor: v2.9.0 | 3.0.x-dev 870f5eb

Additional context

#3

[feature] phpDocumentor v3 compatibility

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Output HTML
• Output Markdown
• Appearance
• Other

Is your feature request related to a problem? Please describe.
Provide compatibility with phpDocumentor 3.

Describe the solution you'd like
Drop compatibility with phpDocumentor 2, which is intended for old PHP versions (<7.2). And provide configuration and documentation for new phpDocumentor 3 and recent PHP versions.

Some names with underscore are not searchables and display without `_` in sidebar

Scopes

• Output HTML
• Output Markdown
• Appearance
• Other

Describe the bug
Names with underscores are misinterpreted as markdown cursive and ignored by sidebars/search box

Steps to reproduce
Steps to reproduce the behavior:

1. Go to '...'
2. Click on '....'
3. Scroll down to '....'
4. See error

Expected behavior

• Display the exact name in sidebar and searchbox as the page
• Search by exact name, including _.

Screenshots

Enviroment:

• OS: [e.g. Fedora 29, Windows 7, etc]
• Browser: [e.g. chrome, safari]

Versions:

• Template: 1.0.0-beta.3
• PHP: 7.2
• Node: 8
• Yarn: 1.13
• VuePress: 0.14.8 | 1.0.0-alpha.32
• phpDocumentor: 2.9.0 | 3.0.0-dev

Posible workaround
Escape _ characters from titles.

Additional context

Report datails in VuePress repo: vuejs/vuepress#1208

Unable to use another route base than '/api/'

[feature] Link 'See Also' section to corresponding doc

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Appearance
• Other

Is your feature request related to a problem? Please describe.
'See also' section refers to elements as plain code instead of links.

Describe the solution you'd like
Make likable the @see tags in order to create links to 'See also' same as the "Inherited methods" section.

[feature] VuePress 1 compatibility

Scopes

• Installation
• Documentation
• Template (twig, xml)
• PHP sources
• Output HTML
• Output Markdown
• Appearance
• Other

Is your feature request related to a problem? Please describe.
VuePress 1

Describe the solution you'd like
Drop compatibility with 0.x VuePress version and use the configuration and format of stable 1.x.