Skip to content

Commit ec2501f

Browse files
nelson6e65nelson6e65
committed
[docs] Improve Configuration page
📝 Improve comments in configuration files
1 parent bfb0c21 commit ec2501f

File tree

4 files changed

+157
-92
lines changed

4 files changed

+157
-92
lines changed

‎data/templates/vuepress/.assets/normalization.css

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11

2-
/* Remove padding and background in element Title */
2+
/* Remove padding and background in <code> used in the structs title */
33
h2 code,
44
h3 code,
55
h4 code,

‎docs/.vuepress/config.js

Lines changed: 29 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,24 @@
11
module.exports = {
2-
// Output build
2+
// Directory where will be generated the HTML files by VuePress
33
dest: 'dist/phpdoc-vuepress/',
4+
5+
// Base URL. Useful for GitHub pages.
46
base: '/phpdoc-vuepress/',
57

8+
// Title of your project
69
title: 'phpdoc-vuepress',
7-
description: 'Template for generating your PHP API documentation in a pretty VuePress format',
8-
ga: 'UA-58599811-1',
910

10-
markdown: {
11-
lineNumbers: false,
12-
toc: { includeLevel: [1, 2, 3] },
13-
},
11+
// Description of your project
12+
description: 'Template for generating your PHP API documentation in a pretty VuePress format',
1413

1514
themeConfig: {
1615
nav: [
17-
{ text: 'Guide', link: '/guide/' }, // Normal documentation link
18-
{ text: 'Demo', link: '/demo/' }, // Your api documentation link
16+
{ text: 'Guide', link: '/guide/' }, // Link to a non-api-documentation section
17+
{ text: 'API (demo)', link: '/demo/' }, // Lint to our API documentation route
1918
],
2019

2120
sidebar: {
22-
'/guide/': [ // Normal documentation
21+
'/guide/': [ // Normal documentation sidebar
2322
{
2423
title: 'Guide',
2524
collapsable: false,
@@ -31,14 +30,15 @@ module.exports = {
3130
}
3231
],
3332

34-
// Your API documentation
33+
// Your API documentation sidebar
3534
// Here is where will be generated your files (`docs/demo/` in this case).
36-
// (This directory should be ignored by Git)
35+
// This is the directory you configured in your `phpdoc.dist.xml` as target
36+
// directory (or `-t` option of phpdoc)
3737
'/demo/': [
3838
{
39-
title: 'Demo', // Title of your API documentation
39+
title: 'API Demo',
4040
collapsable: false,
41-
children: [
41+
children: [ //
4242
'', // Ref. to the `README.md` file
4343
'classes', // Ref. to the `classes.md` file
4444
'interfaces', // Ref. to the `interfaces.md` file
@@ -52,13 +52,26 @@ module.exports = {
5252
''
5353
]
5454
},
55+
56+
57+
// You can ignore the following optional customizations --------------------
58+
59+
markdown: {
60+
lineNumbers: false,
61+
toc: { includeLevel: [1, 2, 3] },
62+
},
63+
5564
sidebarDepth: 3,
5665

5766
lastUpdated: true,
5867

59-
// Repo
68+
evergreen: true,
69+
70+
// Repository configurations
6071
repo: 'nelson6e65/phpdoc-vuepress',
6172
docsDir: 'docs',
62-
editLinks: true
73+
editLinks: true,
74+
75+
ga: 'UA-58599811-1' // GoogleAnalytics ID.
6376
}
6477
}

‎docs/guide/configuration.md

Lines changed: 98 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -2,79 +2,115 @@
22

33
## Configuring phpDocumentor
44

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.
5+
> These instructions are for phpDocumentor 2, but similar approachment will be valid for phpDocumentor 3.
6+
7+
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.
8+
9+
In order to accomplish this, you must create a configuration file named `phpdoc.dist.xml` and setup (1, 2, and 3).
10+
11+
:::tip Template location [3]
12+
If you installed via Composer, the template will be `vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress`.
613

714
```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>
15+
<transformations>
16+
<template name="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" />
17+
</transformations>
2718
```
19+
:::
20+
21+
22+
You can use the configuration of this project as example and guide. Just edit the values that suits your project.
23+
24+
25+
### Example
26+
27+
Here is the explained phpDocumentor configuration for this project:
28+
29+
<<< @/phpdoc.dist.xml
30+
31+
Then, you can just run `phpdoc`.
2832

29-
More information about [configuring phpDocumentor](http://www.phpdoc.org/docs/latest/references/configuration.html).
33+
> For further information, check the [Configuring phpDocumentor page](http://www.phpdoc.org/docs/latest/references/configuration.html).
3034
31-
> Yo can use [`phpdoc.dist.xml`](https://github.com/nelson6e65/phpdoc-vuepress/blob/master/phpdoc.dist.xml) of this repo as a guide.
3235

3336

3437
## Configuring VuePress
3538

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',
39+
If you don't already have configured your VuePress, create **`docs/.vuepress/config.js`** following the ***Config Reference*** according to [v0.x](https://v0.vuepress.vuejs.org/config/) or [v1.x](https://vuepress.vuejs.org/config/) version of VuePress you use.
40+
41+
Once done, you only need to include the files generated by ***phpDocumentor*** in your sidebar as you like.
42+
43+
This template generates this files:
44+
45+
- `README.md`: Introduction to your API documentation. [extra]
46+
- `classes.md`: Documentation of your classes.
47+
- `interfaces.md`: Documentation of your interfaces.
48+
- `traits.md`: Documentation of your traits.
49+
- `functions.md`: Documentation of your global/namespaced functions.
50+
- `constants.md`: Documentation of your global/namespaced constants.
51+
52+
53+
### Example
54+
55+
Here is the explained VuePress configuration for this project. Use it as example and guide:
56+
57+
<<< @/docs/.vuepress/config.js
58+
59+
60+
Then, you can just run `vuepress build docs`.
61+
62+
::: tip
63+
If you installed VuePress as project dependency, you can configure scripts in your `package.json`:
64+
65+
```json
66+
{
67+
"scripts": {
68+
"docs:dev": "vuepress dev docs",
69+
"docs:build": "vuepress build docs"
7470
}
7571
}
7672
```
7773

78-
> Read mor about recommended directory structure at [https://vuepress.vuejs.org/guide/directory-structure.html](https://vuepress.vuejs.org/guide/directory-structure.html)
74+
And then just run `yarn docs:build` :sunglasses:.
75+
:::
76+
77+
> Read about recommended directory structure at [https://vuepress.vuejs.org/guide/directory-structure.html](https://vuepress.vuejs.org/guide/directory-structure.html)
78+
79+
80+
::: warning
81+
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.
82+
:::
83+
84+
85+
## Extras
86+
87+
### Running `phpDocumentor` without a configuration file
88+
89+
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.
90+
91+
For example, if your code is under `demo/` directory and your VuePress resides in `docs/`, and your route `/api/`, you may use:
92+
93+
```
94+
$ phpdoc -d demo/ -t docs/api/ --template=vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress
95+
```
96+
97+
::: warning
98+
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.
99+
:::
100+
101+
::: tip
102+
You can add the command as Composer script:
103+
104+
```json
105+
"scripts": {
106+
"phpdoc": [
107+
"phpdoc -d demo/ -t docs/api/ --template=vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress --ansi"
108+
]
109+
},
110+
```
111+
112+
And then just run `composer phpdoc` :sunglasses:.
113+
114+
:::
79115

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.
116+
> For further information, check the [Runing phpDocumentor documentation](https://docs.phpdoc.org/guides/running-phpdocumentor.html).

‎phpdoc.dist.xml

Lines changed: 29 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -3,28 +3,44 @@
33
<!-- Title of your project. It will be used to show a mini description -->
44
<title>`phpdoc-vuepress` demo</title>
55

6-
<parser>
7-
<visibility>public,protected</visibility>
8-
<target>build/api-cache</target> <!-- This can be set to any directory (remember ignore it by Git) -->
9-
</parser>
6+
<!-- [1]
7+
Directories and files from where will be extracted the documentation;
8+
where your PHP sources are. -->
9+
<files>
10+
<!-- In this case, the soures to document are in the `demo/` dir-->
11+
<directory>demo</directory>
12+
13+
<!-- You can include as many <directory> you need. And also, specific files
14+
by using <file> tag-->
15+
16+
<!-- <file>vendor/cakephp/utility/Text.php</file> -->
17+
</files>
18+
1019

1120
<transformer>
12-
<!-- This is the directory where the generated files will be. -->
13-
<!-- Set it according to your VuePress config -->
21+
<!-- [2]
22+
Directory where the generate documentation files be. Set it according to
23+
your VuePress config. In this case, it will be used the route `/demo`,
24+
but you can use any you want -->
1425
<target>docs/demo</target>
1526
</transformer>
1627

1728
<transformations>
18-
<!-- This is the directory where the template is. -->
19-
<template name="data/templates/vuepress" /> <!-- In this case, the template.xml file is in that directory-->
29+
<!-- [3] Directory where the template.xml is. In this case, the template.xml file is in that directory -->
30+
<template name="data/templates/vuepress" />
2031

21-
<!-- By default, should be set to: "vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" -->
32+
<!-- But in your Composer project, you should use the following line instead of the previous one. -->
2233
<!-- <template name="vendor/nelson6e65/phpdoc-vuepress/data/templates/vuepress" /> -->
2334
</transformations>
2435

25-
<files>
26-
<!-- This is the directory that will be extracted the documentation. In this case. `demo/` -->
27-
<directory>demo</directory>
28-
</files>
2936

37+
<parser>
38+
<!-- [4] Elements to include in your documentation by visibility:
39+
public, protected and private. -->
40+
<visibility>public,protected</visibility>
41+
42+
<!-- Directory where to put the cache. This can be set to any directory.
43+
Remember ignore it by Git -->
44+
<target>build/api-cache</target>
45+
</parser>
3046
</phpdoc>

0 commit comments

Comments
 (0)