Skip to content

Commit 1eb0e6b

Browse files
committed
📝 🆙 Simplify README and improve documentation
1 parent 9f39942 commit 1eb0e6b

File tree

7 files changed

+188
-140
lines changed

7 files changed

+188
-140
lines changed

README.md

Lines changed: 51 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -6,25 +6,42 @@
66
[![Latest Version](https://img.shields.io/packagist/v/nelson6e65/phpdoc-vuepress.svg?label=stable)](https://packagist.org/packages/nelson6e65/phpdoc-vuepress)
77
[![Latest unstable Version](https://img.shields.io/packagist/vpre/nelson6e65/phpdoc-vuepress.svg?label=unstable)](https://packagist.org/packages/nelson6e65/phpdoc-vuepress#dev-master)
88

9-
109
[![License](https://img.shields.io/github/license/nelson6e65/phpdoc-vuepress.svg)](LICENSE)
1110
[![Documentation](http://img.shields.io/badge/📜-Documentation-lightgrey.svg)](http://nelson6e65.github.io/phpdoc-vuepress)
1211

1312

14-
[phpDocumentor template](http://www.phpdoc.org/docs/latest/getting-started/changing-the-look-and-feel.html) that generates [VuePress](https://vuepress.vuejs.org) documentation of your API.
13+
This package provides a **phpDocumentor** template to generates the API documentation of your code to be integrated in a nice looking [VuePress](https://vuepress.vuejs.org) project.
14+
15+
> Only tested with the default theme of VuePress.
1516
16-
The main use-case for this template is to generate simple and nice looking API documentation pages to be integrated in a VuePress project.
17+
## Features
1718

18-
> Only tested in the default theme of VuePress.
19+
This template will generate six VuePress `*.md` files with the DocBlock documentation in your target directory:
1920

20-
> **Special note:** This template is based on Markdown template created by [@cvuorinen](https://github.com/cvuorinen) in [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public).
21+
- `README.md`: Entry point of your API Documentation. Contains, at the moment, an introduction and references to blocks used in the site.
22+
- `classes.md`: Contains all classes, sorted by namespace.
23+
- `interfaces.md`: Contains all interfaces, sorted by namespace.
24+
- `traits.md`: Contains all traits, sorted by namespace.
25+
- `constants.md`: Contains all global constants, sorted by namespace.
26+
- `functions.md`: Contains all global functions, sorted by namespace.
2127

2228

2329
## Demo
2430

25-
Check a demo of documentation generated with this template in https://nelson6e65.github.io/php_nml/api/.
31+
Check a demo of documentation generated with this template in http://nelson6e65.github.io/phpdoc-vuepress/demo/
32+
33+
Explore sources of [nelson6e65/phpdoc-vuepress](https://github.com/nelson6e65/phpdoc-vuepress) to use configuration files as guide.
34+
35+
> A real project API generated using this template: [nelson6e65.github.io/php_nml/api/](https://nelson6e65.github.io/php_nml/api/).
2636
27-
> See also the sources in [nelson6e65/php_nml](https://github.com/nelson6e65/php_nml) repo for configuration examples.
37+
38+
## Requirements
39+
40+
- PHP >= 5.6
41+
- Node.js >= 8
42+
- [phpDocumentor](https://www.phpdoc.org/). This template is designed for **phpDocumentor2** (is also compatible with upcoming **phpDocumentor3** for PHP 7.1+ project). You can install it with composer as global requirement: `composer global require phpdocumentor/phpdocumentor`.
43+
- [Yarn](https://yarnpkg.com) (or npm). To build the entire documentation with `vuepress`.
44+
- [VuePress](https://v0.vuepress.vuejs.org/). `v0.x`, but may be compatible with upcoming `v1.0.0`.
2845

2946

3047
## Installation
@@ -35,38 +52,33 @@ Install with composer:
3552
composer require --dev nelson6e65/phpdoc-vuepress
3653
```
3754

38-
39-
> At the moment, this package has not PHP dependencies for usage,
40-
4155
> You may need to set the composer option [minimum-stability](https://getcomposer.org/doc/04-schema.md#minimum-stability) to 'dev' in order to be able to install pre-releases.
4256
43-
## Usage
4457

45-
> Is highly recommended to use a global installation of `phpdoc`, vua composer global (`composer global require --dev phpdocumentor/phpdocumentor`) or the `.phar` file.
58+
## Usage
4659

47-
Run phpDocumentor and set template as `vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress`.
60+
Run phpDocumentor and set template as `vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress`:
4861

4962

5063
```bash
5164
phpdoc -d="src/" -t="docs/api/" --template="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress"
5265
```
5366

54-
More information about the available arguments can be found at [running phpDocumentor](http://www.phpdoc.org/docs/latest/guides/running-phpdocumentor.html).
67+
> More information about the available arguments can be found at [running phpDocumentor](http://www.phpdoc.org/docs/latest/guides/running-phpdocumentor.html).
68+
5569

5670
## Setup
5771

5872
### Configuring phpdoc
5973

60-
https://github.com/nelson6e65/php_nml/blob/master/phpcs.xml
61-
6274
Add a file called `phpdoc.xml` with the following content to the root of your project and invoke the `phpdoc` command without arguments. Modify the configuration to suit your project.
6375

6476
```xml
6577
<?xml version="1.0" encoding="UTF-8" ?>
6678
<phpdoc>
6779
<parser>
6880
<visibility>public,protected</visibility>
69-
<target>output/doc</target>
81+
<target>build/api-cache</target>
7082
</parser>
7183

7284
<transformer>
@@ -85,23 +97,20 @@ Add a file called `phpdoc.xml` with the following content to the root of your pr
8597

8698
More information about [configuring phpDocumentor](http://www.phpdoc.org/docs/latest/references/configuration.html).
8799

88-
### Configure routes in VuePress
89-
90-
Create **`docs/.vuepress/config.js`**
91-
100+
> Yo can use [`phpdoc.dist.xml`](phpdoc.dist.xml) of this repo as a guide.
92101
93102

103+
### Configure routes in VuePress
94104

105+
Create a **`docs/.vuepress/config.js`** file like this:
95106

96107
```js
97108
module.exports = {
98-
// Output build
99-
dest: 'output/docs/php_nml',
100-
base: '/php_nml/',
109+
dest: 'dist/phpdoc-vuepress',
110+
base: '/phpdoc-vuepress/',
101111

102112
markdown: {
103113
lineNumbers: false,
104-
toc: { includeLevel: [1, 2, 3] },
105114
},
106115

107116
themeConfig: {
@@ -110,7 +119,7 @@ module.exports = {
110119
],
111120

112121
sidebar: {
113-
'/api/': [
122+
'/api/': [ // `docs/api/` directory
114123
{
115124
title: 'API',
116125
collapsable: false,
@@ -130,34 +139,27 @@ module.exports = {
130139
},
131140
sidebarDepth: 3,
132141

133-
// Repo
134-
repo: 'nelson6e65/php_nml',
135-
docsDir: 'docs',
136-
editLinks: true
142+
docsDir: 'docs',
137143
}
138144
}
139145
```
140146

141-
> Extract from [docs/.vuepress/config.js](https://github.com/nelson6e65/php_nml/blob/master/docs/.vuepress/config.js)
142-
143147
> Read mor about recommended directory structure at https://vuepress.vuejs.org/guide/directory-structure.html
144148
145-
## Recommendations
149+
> You can use [`docs/.vuepress/config.js`](docs/.vuepress/config.js) used in this repo as an example.
146150
147-
- **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`:
148-
```bash
149-
# Autogenerated API documentation
150-
docs/api/
151-
```
152151

153-
- **Restrict visibility to protected members**. By default, all members are parsed. So, you need to config `--visibility` to ignore `private` methods:
154-
```bash
155-
phpdoc --visibility="public,protected"
156-
```
157-
or
158-
```xml
159-
<parser>
160-
<!-- Only Public and Protected members are parsed -->
161-
<visibility>public,protected</visibility>
162-
</parser>
163-
```
152+
## Further reading
153+
154+
Check the documentation for more information [https://nelson6e65.github.io/phpdoc-vuepress/](https://nelson6e65.github.io/phpdoc-vuepress/).
155+
156+
157+
## License
158+
159+
[![License](https://img.shields.io/github/license/nelson6e65/phpdoc-vuepress.svg)](LICENSE)
160+
161+
Copyright (c) 2018-2019 Nelson Martell
162+
163+
Read the [`LICENSE` file](LICENSE) for details.
164+
165+
> **Note:** This template is based on Markdown template created by [@cvuorinen](https://github.com/cvuorinen): [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public).

docs/.vuepress/config.js

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ module.exports = {
2626
children: [
2727
'',
2828
'getting-started',
29+
'configuration',
2930
]
3031
}
3132
],

docs/README.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
home: true
33
heroText: "phpdoc-vuepress"
4-
tagline: VuePress template for phpDocumentor
4+
tagline: Template for generating your PHP API documentation in a VuePress format.
55
actionText: Get Started →
66
actionLink: /guide/
77

docs/guide/README.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,40 @@
99
::: tip phpdoc-vuepress
1010
VuePress template for phpDocumentor.
1111
:::
12+
13+
This package provides a **phpDocumentor** template to generates the API documentation of your code to be integrated in a nice looking [VuePress](https://vuepress.vuejs.org) project.
14+
15+
> Only tested with the default theme of VuePress.
16+
17+
18+
## Features
19+
20+
This template will generate six VuePress `*.md` files with the DocBlock documentation in your target directory:
21+
22+
- `README.md`: Entry point of your API Documentation. Contains, at the moment, an introduction and references to blocks used in the site.
23+
- `classes.md`: Contains all classes, sorted by namespace.
24+
- `interfaces.md`: Contains all interfaces, sorted by namespace.
25+
- `traits.md`: Contains all traits, sorted by namespace.
26+
- `constants.md`: Contains all global constants, sorted by namespace.
27+
- `functions.md`: Contains all global functions, sorted by namespace.
28+
29+
30+
31+
## Demo
32+
33+
Check a demo of documentation generated with this template in [Demo](/demo/)
34+
35+
Explore sources of [nelson6e65/phpdoc-vuepress](https://github.com/nelson6e65/phpdoc-vuepress) to use configuration files as guide.
36+
37+
> A real project API generated using this template: [nelson6e65.github.io/php_nml/api/](https://nelson6e65.github.io/php_nml/api/).
38+
39+
40+
## License
41+
42+
![License](https://img.shields.io/github/license/nelson6e65/phpdoc-vuepress.svg)
43+
44+
Copyright (c) 2018-2019 Nelson Martell
45+
46+
Read the [`LICENSE` file](https://github.com/nelson6e65/phpdoc-vuepress/blob/master/LICENSE) for details.
47+
48+
> **Note:** This template is based on Markdown template created by [@cvuorinen](https://github.com/cvuorinen): [cvuorinen/phpdoc-markdown-public](https://github.com/cvuorinen/phpdoc-markdown-public).

docs/guide/configuration.md

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
# Configuration
2+
3+
## Configuring phpDocumentor
4+
5+
Add a file called `phpdoc.xml` with the following content to the root of your project and invoke the `phpdoc` command without arguments. Modify the configuration to suit your project.
6+
7+
```xml
8+
<?xml version="1.0" encoding="UTF-8" ?>
9+
<phpdoc>
10+
<parser>
11+
<visibility>public,protected</visibility>
12+
<target>build/api-cache</target>
13+
</parser>
14+
15+
<transformer>
16+
<target>docs/api</target>
17+
</transformer>
18+
19+
<transformations>
20+
<template name="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" />
21+
</transformations>
22+
23+
<files>
24+
<directory>src</directory>
25+
</files>
26+
</phpdoc>
27+
```
28+
29+
More information about [configuring phpDocumentor](http://www.phpdoc.org/docs/latest/references/configuration.html).
30+
31+
> Yo can use [`phpdoc.dist.xml`](https://github.com/nelson6e65/phpdoc-vuepress/blob/master/phpdoc.dist.xml) of this repo as a guide.
32+
33+
34+
## Configuring VuePress
35+
36+
Create a **`docs/.vuepress/config.js`** file like this:
37+
38+
```js
39+
module.exports = {
40+
dest: 'dist/phpdoc-vuepress',
41+
base: '/phpdoc-vuepress/',
42+
43+
markdown: {
44+
lineNumbers: false,
45+
},
46+
47+
themeConfig: {
48+
nav: [
49+
{ text: 'API', link: '/api/' },
50+
],
51+
52+
sidebar: {
53+
'/api/': [ // `docs/api/` directory
54+
{
55+
title: 'API',
56+
collapsable: false,
57+
children: [
58+
'',
59+
'classes',
60+
'interfaces',
61+
'traits',
62+
'functions',
63+
'constants'
64+
]
65+
}
66+
],
67+
'/': [
68+
''
69+
]
70+
},
71+
sidebarDepth: 3,
72+
73+
docsDir: 'docs',
74+
}
75+
}
76+
```
77+
78+
> Read mor about recommended directory structure at [https://vuepress.vuejs.org/guide/directory-structure.html](https://vuepress.vuejs.org/guide/directory-structure.html)
79+
80+
> You can use [`docs/.vuepress/config.js`](https://github.com/nelson6e65/phpdoc-vuepress/blob/master/docs/.vuepress/config.js) used in this repo as an example.

0 commit comments

Comments
 (0)