Skip to content

Commit 7b5b1ce

Browse files
ph1pph1p
committed
feat(readme): add ability to add a custom readme
1 parent d643781 commit 7b5b1ce

File tree

16 files changed

+172
-155
lines changed

16 files changed

+172
-155
lines changed

‎README.md

Lines changed: 14 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -28,13 +28,14 @@ If no command passed it will run `generate` as default
2828
### Options
2929

3030
| Name | Alias | Default | Description |
31-
| -------- | ----- | --------------- | ------------------------------------------------------------ |
31+
| --------- | ----- | --------------- | ------------------------------------------------------------ |
3232
| --source | -s | ./src | Source folder with .js or .ts files |
3333
| --dist | -d | ./documentation | Destination folder |
3434
| --folder | -f | ./code | Folder inside destination folder. Gets overwritten everytime |
3535
| --title | -t | API | Title of your documentation |
3636
| --help | -h | | Show help |
3737
| --version | -v | | Show current version |
38+
| --readme | -r | | Path to custom readme file |
3839

3940
### config.js
4041

@@ -92,13 +93,18 @@ module.exports = {
9293
}
9394
],
9495
// Add the generated sidebar
95-
sidebar: Object.assign({}, sidebarTree)
96+
sidebar: Object.assign({}, sidebarTree('Mainpage title'))
9697
}
9798
}
9899
}
99100
};
100101
```
101102

103+
## Custom readme
104+
105+
You can easily add a custom readme by passing the `--readme` parameter or place a `README.md` inside your source folder.
106+
You can set the title by passing it to the `sidebarTree('Mainpage title')` function.
107+
102108
## @vuepress comment block
103109

104110
You can add custom meta data to your pages
@@ -108,13 +114,12 @@ Simply add:
108114
/*
109115
* @vuepress
110116
* ---
111-
* title: You Custom Title
117+
* title: Your custom title
112118
* ---
113119
*/
114120
```
115121

116-
More inromation: https://vuepress.vuejs.org/guide/markdown.html#front-matter
117-
122+
More information: https://vuepress.vuejs.org/guide/markdown.html#front-matter
118123

119124
## Example
120125

@@ -128,17 +133,11 @@ yarn
128133
vuepress-jsdoc
129134

130135
# Generate docs
131-
yarn run docs
136+
yarn docs
132137

133138
# Run dev server
134-
yarn run dev
139+
yarn dev
135140

136141
# Generate dist folder
137-
yarn run build
138-
```
139-
140-
## ToDo
141-
142-
- [ ] Update description README.md
143-
- [ ] Custom README.md
144-
- [x] Custom meta data
142+
yarn build
143+
```

‎cmds/generate.js

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@ function generate(argv) {
2222
const codeFolder = argv.folder;
2323
const docsFolder = `${argv.dist}/${codeFolder}`;
2424
const title = argv.title;
25+
const readme = argv.readme;
2526

2627
// remove docs folder
2728
rimraf(docsFolder, () =>
@@ -32,12 +33,26 @@ function generate(argv) {
3233

3334
await fs.writeFile(
3435
`${docsFolder}/config.js`,
35-
`exports.fileTree=${JSON.stringify(fileTree, null, 4)};
36-
exports.sidebarTree=${JSON.stringify(vueSidebar({ fileTree, codeFolder, title }), null, 4)};`
36+
`exports.fileTree=${JSON.stringify(fileTree)};exports.sidebarTree = (title = 'Mainpage') => (${JSON.stringify(
37+
vueSidebar({
38+
fileTree,
39+
codeFolder,
40+
title
41+
})
42+
).replace('::vuepress-jsdoc-title::', '"+title+"')});`
3743
);
3844

3945
// create README.md
40-
await fs.writeFile(`${docsFolder}/README.md`, `Welcome`);
46+
let readMeContent = 'Welcome';
47+
let readmePath = readme || `${srcFolder}/README.md`;
48+
49+
try {
50+
readMeContent = await fs.readFile(readmePath, 'utf-8');
51+
} catch (e) {
52+
console.log('INFO: There is no custom readme file.');
53+
}
54+
55+
await fs.writeFile(`${docsFolder}/README.md`, readMeContent);
4156
})
4257
);
4358

‎example/documentation/.vuepress/config.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ module.exports = {
2222
],
2323
// Add the generated sidebar
2424
sidebar: {
25-
...sidebarTree
25+
...sidebarTree('Test')
2626
}
2727
}
2828
}

‎example/documentation/code/README.md

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,9 @@
1-
Welcome
1+
# Home
2+
3+
## Section 1
4+
5+
Section 1
6+
7+
## Section 2
8+
9+
Section 2

‎example/documentation/code/class.md

Lines changed: 15 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
2-
title: My Test Class
2+
title: test class
33
---
44
<a name="Test"></a>
55

6-
## Test**Kind**: global class
6+
## Test
7+
**Kind**: global class
78

89
* [Test](#Test)
910
* [new Test()](#new_Test_new)
@@ -17,30 +18,36 @@ title: My Test Class
1718

1819
<a name="new_Test_new"></a>
1920

20-
### new Test()This is a test class
21+
### new Test()
22+
This is a test class
2123

2224
<a name="Test+name"></a>
2325

24-
### test.nameSet current name
26+
### test.name
27+
Set current name
2528

2629
**Kind**: instance property of [<code>Test</code>](#Test)
2730
<a name="Test+name"></a>
2831

29-
### test.nameGet current name
32+
### test.name
33+
Get current name
3034

3135
**Kind**: instance property of [<code>Test</code>](#Test)
3236
<a name="Test+generateFullName"></a>
3337

34-
### test.generateFullName() ⇒Generate a fullname
38+
### test.generateFullName() ⇒
39+
Generate a fullname
3540

3641
**Kind**: instance method of [<code>Test</code>](#Test)
3742
**Returns**: an string
3843
<a name="Test.Test"></a>
3944

40-
### Test.Test**Kind**: static class of [<code>Test</code>](#Test)
45+
### Test.Test
46+
**Kind**: static class of [<code>Test</code>](#Test)
4147
<a name="new_Test.Test_new"></a>
4248

43-
#### new Test([name])Creates an instance of Test.
49+
#### new Test([name])
50+
Creates an instance of Test.
4451

4552

4653
| Param | Type | Default |

‎example/documentation/code/config.js

Lines changed: 29 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,30 @@
1-
exports.fileTree=[
2-
{
3-
"name": "class",
4-
"path": "/class",
5-
"fullPath": "./documentation/code/class"
6-
},
7-
{
8-
"name": "lib",
9-
"children": [
10-
{
11-
"name": "dmd-options",
12-
"path": "/dmd-options",
13-
"fullPath": "lib/dmd-options"
14-
},
15-
{
16-
"name": "jsdoc-to-markdown",
17-
"path": "/jsdoc-to-markdown",
18-
"fullPath": "lib/jsdoc-to-markdown"
19-
}
20-
]
21-
},
22-
{
23-
"name": "methods",
24-
"path": "/methods",
25-
"fullPath": "./documentation/code/methods"
26-
},
27-
{
28-
"name": "objects",
29-
"path": "/objects",
30-
"fullPath": "./documentation/code/objects"
31-
},
32-
{
33-
"name": "subfolder",
34-
"children": [
35-
{
36-
"name": "subfolder.1",
37-
"children": [
38-
{
39-
"name": "variables",
40-
"path": "/variables",
41-
"fullPath": "subfolder/subfolder.1/variables"
42-
}
43-
]
44-
},
45-
{
46-
"name": "variables",
47-
"path": "/variables",
48-
"fullPath": "subfolder/variables"
49-
}
50-
]
51-
},
52-
{
53-
"name": "test",
54-
"path": "/test",
55-
"fullPath": "./documentation/code/test"
56-
}
57-
];
58-
exports.sidebarTree={
59-
"/code/": [
60-
{
61-
"title": "API",
62-
"collapsable": false,
63-
"children": [
64-
[
65-
"",
66-
"Mainpage"
67-
],
68-
"class",
69-
"methods",
70-
"objects",
71-
"test"
72-
]
73-
},
74-
{
75-
"title": "lib",
76-
"collapsable": false,
77-
"children": [
78-
"lib/dmd-options",
79-
"lib/jsdoc-to-markdown"
80-
]
81-
},
82-
{
83-
"title": "subfolder",
84-
"collapsable": false,
85-
"children": [
86-
"subfolder/subfolder.1/variables",
87-
"subfolder/variables"
88-
]
89-
}
1+
exports.fileTree = [
2+
{ name: 'class', path: '/class', fullPath: './documentation/code/class' },
3+
{
4+
name: 'lib',
5+
children: [
6+
{ name: 'dmd-options', path: '/dmd-options', fullPath: 'lib/dmd-options' },
7+
{ name: 'jsdoc-to-markdown', path: '/jsdoc-to-markdown', fullPath: 'lib/jsdoc-to-markdown' }
8+
]
9+
},
10+
{ name: 'methods', path: '/methods', fullPath: './documentation/code/methods' },
11+
{ name: 'objects', path: '/objects', fullPath: './documentation/code/objects' },
12+
{
13+
name: 'subfolder',
14+
children: [
15+
{
16+
name: 'subfolder.1',
17+
children: [{ name: 'variables', path: '/variables', fullPath: 'subfolder/subfolder.1/variables' }]
18+
},
19+
{ name: 'variables', path: '/variables', fullPath: 'subfolder/variables' }
9020
]
91-
};
21+
},
22+
{ name: 'test', path: '/test', fullPath: './documentation/code/test' }
23+
];
24+
exports.sidebarTree = (title = 'Mainpage') => ({
25+
'/code/': [
26+
{ title: 'API', collapsable: false, children: [['', '' + title + ''], 'class', 'methods', 'objects', 'test'] },
27+
{ title: 'lib', collapsable: false, children: ['lib/dmd-options', 'lib/jsdoc-to-markdown'] },
28+
{ title: 'subfolder', collapsable: false, children: ['subfolder/subfolder.1/variables', 'subfolder/variables'] }
29+
]
30+
});

‎example/documentation/code/lib/dmd-options.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,4 +3,5 @@ title: dmd-options
33
---
44
<a name="DmdOptions"></a>
55

6-
## DmdOptions**Kind**: global class
6+
## DmdOptions
7+
**Kind**: global class

0 commit comments

Comments
 (0)