Skip to content

Commit 6c93149

Browse files
ph1pph1p
committed
docs: document vuepress-jsdoc with itself
1 parent 227b46b commit 6c93149

File tree

16 files changed

+638
-3
lines changed

16 files changed

+638
-3
lines changed

‎documentation/.vuepress/config.js‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
const { sidebarTree } = require('../code/config');
2+
3+
module.exports = {
4+
contentLoading: true,
5+
dest: 'public',
6+
title: 'vuepress-jsdoc',
7+
description: 'vuepress-jsdoc documented with itself',
8+
plugins: [
9+
[
10+
// require('vuepress-jsdoc')
11+
require('../../dist/index.js').default,
12+
{
13+
folder: 'code',
14+
jsDocConfigPath: './jsdoc.json',
15+
source: './src',
16+
dist: './documentation',
17+
title: 'API'
18+
}
19+
]
20+
],
21+
locales: {
22+
'/': {
23+
title: 'vuepress-jsdoc',
24+
description: 'A CLI to create jsdoc md files for vuepress'
25+
}
26+
},
27+
themeConfig: {
28+
sidebarDepth: 4,
29+
locales: {
30+
'/': {
31+
nav: [
32+
{
33+
text: 'Home',
34+
link: '/'
35+
}
36+
],
37+
// Add the generated sidebar
38+
sidebar: {
39+
...sidebarTree('Readme')
40+
}
41+
}
42+
}
43+
}
44+
};

‎documentation/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
home: true
3+
actionText: Get Started →
4+
actionLink: /code/
5+
---

‎documentation/code/README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# vuepress-jsdoc
2+
3+
[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=ph1p_vuepress-jsdoc&metric=alert_status)](https://sonarcloud.io/dashboard?id=ph1p_vuepress-jsdoc)
4+
[![npm](https://img.shields.io/npm/v/vuepress-jsdoc.svg)](https://www.npmjs.com/package/vuepress-jsdoc)
5+
[![vercel](https://img.shields.io/badge/vercel-demo-black)](https://vuepress-jsdoc-example.vercel.app)
6+
7+
This npm package is a command line script, which scans your JavaScript, Vue or Typescript source code and generates markdown files for vuepress with the help of [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown) and [vue-docgen-cli](https://github.com/vue-styleguidist/vue-styleguidist/tree/dev/packages/vue-docgen-cli).
8+
9+
![CLI ./example](https://user-images.githubusercontent.com/15351728/131877824-0124e47f-9080-4976-88d0-84ad04b64f24.gif)
10+
11+
## How to
12+
13+
```bash
14+
yarn global add vuepress-jsdoc
15+
npm i vuepress-jsdoc -g
16+
```
17+
18+
**Example:**
19+
20+
```bash
21+
# search code in src and move it to code (./documentation/code) in your vuepress folder (./documentation)
22+
vuepress-jsdoc --source ./src --dist ./documentation --folder code --title API --exclude=**/*/*.test.js
23+
```
24+
25+
#### Plugin (Dev-Mode) `alpha`
26+
27+
You can use `vuepress-jsdoc` also as plugin.
28+
This plugin watches you generated files.
29+
30+
```javascript
31+
// .vuepress/config.js
32+
plugins: [
33+
[
34+
require('vuepress-jsdoc').default,
35+
{
36+
folder: 'code',
37+
jsDocConfigPath: './jsdoc.json',
38+
source: './src',
39+
dist: './documentation',
40+
title: 'API'
41+
}
42+
]
43+
];
44+
```
45+
46+
#### Watch-Mode `alpha`
47+
48+
If you do not want to run`vuepress-jsdoc` again and again and again.
49+
You can simply pass `--watch` or `-w`.
50+
51+
### Commands
52+
53+
If no command passed it will run `generate` as default
54+
55+
| Name | Alias | Description |
56+
| -------- | ------ | ------------------------------------------------------------------------------------------------------- |
57+
| generate | gen, g | search code in src and move it to code (./documentation/code) in your vuepress folder (./documentation) |
58+
59+
### Options
60+
61+
| Name | Alias | Default | Description |
62+
| ----------------- | ----- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
63+
| --source | -s | ./src | Source folder with .js or .ts files |
64+
| --dist | -d | ./documentation | Destination folder |
65+
| --folder | -f | ./code | Folder inside destination folder. Gets overwritten everytime |
66+
| --title | -t | API | Title of your documentation |
67+
| --help | -h | | Show help |
68+
| --version | -v | | Show current version |
69+
| --readme | -r | | Path to custom readme file |
70+
| --exclude | -e | | Pattern to exclude files/folders (Comma seperated) - \*.test.js,exclude.js [more information](https://github.com/micromatch/micromatch#ismatch) |
71+
| --rmPattern | -rm | | Pattern when removing files. You can ex- and include files. (glob pattern) |
72+
| --partials | -p | | jsdoc2markdown partial templates (overwrites default ones) |
73+
| --jsDocConfigPath | -c | | Path to [JsDoc Config](http://usejsdoc.org/about-configuring-jsdoc.html) (experimental) |
74+
| --watch | -w | | Watch changes and update markdown files |
75+
76+
### config.js
77+
78+
Inside your generated folder, you can find a `config.js`.
79+
This file includes a complete filetree and an vuepress sidebar tree.
80+
81+
## How to configure vuepress
82+
83+
[Vuepress](https://vuepress.vuejs.org/) is a static site generator by Evan You.
84+
You can add all generated documentation files to your existing vuepress project or create a new one.
85+
86+
```bash
87+
# First install vuepress
88+
yarn global add vuepress
89+
90+
# Run the CLI
91+
vuepress-jsdoc
92+
93+
# Run vuepress dev server
94+
vuepress dev ./documentation
95+
96+
# Run vuepress build, if you want to ship it
97+
vuepress build ./documentation
98+
```
99+
100+
**Access it via:** [http://localhost:8080/code/](http://localhost:8080/code/)
101+
102+
Now you need the sidebar.
103+
Create a `.vuepress` folder inside the `documentation` folder and add the following `config.js`.
104+
105+
**config.js:**
106+
107+
```javascript
108+
// auto generated sidebar
109+
const { sidebarTree } = require('../code/config');
110+
111+
module.exports = {
112+
dest: 'dist',
113+
locales: {
114+
'/': {
115+
title: 'vuepress-jsdoc',
116+
description: 'Generate jsdoc markdown files for vuepress'
117+
}
118+
},
119+
themeConfig: {
120+
editLinks: true,
121+
sidebarDepth: 4,
122+
docsDir: 'code',
123+
locales: {
124+
'/': {
125+
nav: [
126+
{
127+
text: 'Home',
128+
link: '/'
129+
}
130+
],
131+
// Add the generated sidebar
132+
sidebar: Object.assign({}, sidebarTree('Mainpage title'))
133+
}
134+
}
135+
}
136+
};
137+
```
138+
139+
## Custom readme
140+
141+
You can easily add a custom path to your readme by using the `--readme ./path/to/file.md` parameter. If you move a `README.md` inside your source folder, it should resolve it automatically.
142+
You can set the title by passing it to the `sidebarTree('Mainpage title')` function inside your `./.vuepress/config.js`.
143+
144+
Once the README.md has been added, it is no longer overwritten!
145+
If you want it to be overwritten, set `--rmPattern=./documentation/code/README.md`.
146+
147+
## @vuepress comment block
148+
149+
You can add custom meta data to your pages by using the `@vuepress` block:
150+
151+
```javascript
152+
/*
153+
* @vuepress
154+
* ---
155+
* title: Your custom title
156+
* headline: You custom headline
157+
* ---
158+
*/
159+
```
160+
161+
Use `headline` to add a custom `h1` title.
162+
163+
[More information](https://vuepress.vuejs.org/guide/markdown.html#front-matter)
164+
165+
## Typescript
166+
167+
To use typescript, you have to install these dev-dependencies:
168+
169+
```bash
170+
yarn add -D typescript jsdoc-babel @babel/cli @babel/core @babel/preset-env @babel/preset-typescript jsdoc-to-markdown
171+
```
172+
173+
Next, you have to add a `jsdoc.json` to your project with some settings and add it with the `-c` parameter.
174+
You can find a full working example with all settings inside the `./example` folder.
175+
The example shows also how to use babel-`plugins`.
176+
177+
## Example
178+
179+
The `./example` folder includes a full working vuepress-jsdoc example.
180+
181+
```bash
182+
# Install dependencies
183+
npm install
184+
185+
# Run the CLI
186+
vuepress-jsdoc
187+
188+
# Generate docs
189+
npm run docs
190+
191+
# Run dev server
192+
npm run dev
193+
194+
# Generate dist folder
195+
npm run build
196+
```
197+
198+
## Contribute
199+
200+
PRs are always welcome (:

‎documentation/code/__index__.md‎

Lines changed: 88 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
---
2+
title: Main
3+
headline: The Main File
4+
---
5+
6+
# The Main File
7+
8+
## Functions
9+
10+
<dl>
11+
<dt><a href="#createVuepressSidebar">createVuepressSidebar(options)</a> ⇒</dt>
12+
<dd><p>Create the sidebar</p>
13+
</dd>
14+
<dt><a href="#parseDirectoryFile">parseDirectoryFile(file, argv)</a> ⇒</dt>
15+
<dd><p>Parse file</p>
16+
</dd>
17+
<dt><a href="#parseArguments">parseArguments(argv)</a> ⇒</dt>
18+
<dd><p>Parse all CLI arguments</p>
19+
</dd>
20+
<dt><a href="#generate">generate(argv)</a></dt>
21+
<dd><p>Default command that generate md files</p>
22+
</dd>
23+
<dt><a href="#plugin">plugin(argv, ctx)</a> ⇒</dt>
24+
<dd><p>The vuepress plugins</p>
25+
</dd>
26+
</dl>
27+
28+
<a name="createVuepressSidebar"></a>
29+
30+
## createVuepressSidebar(options) ⇒
31+
Create the sidebar
32+
33+
**Kind**: global function
34+
**Returns**: Promise
35+
36+
| Param |
37+
| --- |
38+
| options |
39+
40+
<a name="parseDirectoryFile"></a>
41+
42+
## parseDirectoryFile(file, argv) ⇒
43+
Parse file
44+
45+
**Kind**: global function
46+
**Returns**: Promise
47+
48+
| Param |
49+
| --- |
50+
| file |
51+
| argv |
52+
53+
<a name="parseArguments"></a>
54+
55+
## parseArguments(argv) ⇒
56+
Parse all CLI arguments
57+
58+
**Kind**: global function
59+
**Returns**: all arguments
60+
61+
| Param |
62+
| --- |
63+
| argv |
64+
65+
<a name="generate"></a>
66+
67+
## generate(argv)
68+
Default command that generate md files
69+
70+
**Kind**: global function
71+
72+
| Param | Type | Description |
73+
| --- | --- | --- |
74+
| argv | <code>object</code> | passed arguments |
75+
76+
<a name="plugin"></a>
77+
78+
## plugin(argv, ctx) ⇒
79+
The vuepress plugins
80+
81+
**Kind**: global function
82+
**Returns**: plugin
83+
84+
| Param |
85+
| --- |
86+
| argv |
87+
| ctx |
88+

‎documentation/code/config.js‎

Lines changed: 1 addition & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎documentation/code/lib/comment-parser.md‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: comment-parser
3+
---
4+
5+
# comment-parser
6+
7+
## Functions
8+
9+
<dl>
10+
<dt><a href="#parseComment">parseComment(fileContent)</a> ⇒</dt>
11+
<dd><p>Search in file for @vuepress comment</p>
12+
</dd>
13+
<dt><a href="#parseVuepressFileHeader">parseVuepressFileHeader(content, file)</a> ⇒</dt>
14+
<dd><p>Helper function to get header as strctured markdown</p>
15+
</dd>
16+
</dl>
17+
18+
<a name="parseComment"></a>
19+
20+
## parseComment(fileContent) ⇒
21+
Search in file for @vuepress comment
22+
23+
**Kind**: global function
24+
**Returns**: object of found frontmatter data
25+
26+
| Param |
27+
| --- |
28+
| fileContent |
29+
30+
<a name="parseVuepressFileHeader"></a>
31+
32+
## parseVuepressFileHeader(content, file) ⇒
33+
Helper function to get header as strctured markdown
34+
35+
**Kind**: global function
36+
**Returns**: markdown header
37+
38+
| Param | Description |
39+
| --- | --- |
40+
| content | : ; |
41+
| file | |
42+

0 commit comments

Comments
 (0)