You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[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.
15
16
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
17
18
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:
19
20
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.
21
27
22
28
23
29
## Demo
24
30
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/).
26
36
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`.
28
45
29
46
30
47
## Installation
@@ -35,38 +52,33 @@ Install with composer:
35
52
composer require --dev nelson6e65/phpdoc-vuepress
36
53
```
37
54
38
-
39
-
> At the moment, this package has not PHP dependencies for usage,
40
-
41
55
> 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.
42
56
43
-
## Usage
44
57
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
46
59
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`:
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).
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.
63
75
64
76
```xml
65
77
<?xml version="1.0" encoding="UTF-8" ?>
66
78
<phpdoc>
67
79
<parser>
68
80
<visibility>public,protected</visibility>
69
-
<target>output/doc</target>
81
+
<target>build/api-cache</target>
70
82
</parser>
71
83
72
84
<transformer>
@@ -85,23 +97,20 @@ Add a file called `phpdoc.xml` with the following content to the root of your pr
85
97
86
98
More information about [configuring phpDocumentor](http://www.phpdoc.org/docs/latest/references/configuration.html).
87
99
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.
92
101
93
102
103
+
### Configure routes in VuePress
94
104
105
+
Create a **`docs/.vuepress/config.js`** file like this:
95
106
96
107
```js
97
108
module.exports= {
98
-
// Output build
99
-
dest:'output/docs/php_nml',
100
-
base:'/php_nml/',
109
+
dest:'dist/phpdoc-vuepress',
110
+
base:'/phpdoc-vuepress/',
101
111
102
112
markdown: {
103
113
lineNumbers:false,
104
-
toc: { includeLevel: [1, 2, 3] },
105
114
},
106
115
107
116
themeConfig: {
@@ -110,7 +119,7 @@ module.exports = {
110
119
],
111
120
112
121
sidebar: {
113
-
'/api/': [
122
+
'/api/': [// `docs/api/` directory
114
123
{
115
124
title:'API',
116
125
collapsable:false,
@@ -130,34 +139,27 @@ module.exports = {
130
139
},
131
140
sidebarDepth:3,
132
141
133
-
// Repo
134
-
repo:'nelson6e65/php_nml',
135
-
docsDir:'docs',
136
-
editLinks:true
142
+
docsDir:'docs',
137
143
}
138
144
}
139
145
```
140
146
141
-
> Extract from [docs/.vuepress/config.js](https://github.com/nelson6e65/php_nml/blob/master/docs/.vuepress/config.js)
142
-
143
147
> Read mor about recommended directory structure at https://vuepress.vuejs.org/guide/directory-structure.html
144
148
145
-
## Recommendations
149
+
> You can use [`docs/.vuepress/config.js`](docs/.vuepress/config.js) used in this repo as an example.
146
150
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
-
```
152
151
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/).
> **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).
Copy file name to clipboardExpand all lines: docs/guide/README.md
+37Lines changed: 37 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -9,3 +9,40 @@
9
9
::: tip phpdoc-vuepress
10
10
VuePress template for phpDocumentor.
11
11
:::
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/).
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).
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.
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