feat(readme): add ability to add a custom readme

ph1p · Dec 18, 2018 · 7b5b1ce · 7b5b1ce
1 parent d643781
commit 7b5b1ce
Show file tree

Hide file tree

Showing 16 changed files with 172 additions and 155 deletions.
diff --git a/README.md b/README.md
@@ -28,13 +28,14 @@ If no command passed it will run `generate` as default
 ### Options
 
 | Name      | Alias | Default         | Description                                                  |
-| --------  | ----- | --------------- | ------------------------------------------------------------ |
+| --------- | ----- | --------------- | ------------------------------------------------------------ |
 | --source  | -s    | ./src           | Source folder with .js or .ts files                          |
 | --dist    | -d    | ./documentation | Destination folder                                           |
 | --folder  | -f    | ./code          | Folder inside destination folder. Gets overwritten everytime |
 | --title   | -t    | API             | Title of your documentation                                  |
 | --help    | -h    |                 | Show help                                                    |
 | --version | -v    |                 | Show current version                                         |
+| --readme  | -r    |                 | Path to custom readme file                                   |
 
 ### config.js
 
@@ -92,13 +93,18 @@ module.exports = {
           }
         ],
         // Add the generated sidebar
-        sidebar: Object.assign({}, sidebarTree)
+        sidebar: Object.assign({}, sidebarTree('Mainpage title'))
       }
     }
   }
 };
 ```
 
+## Custom readme
+
+You can easily add a custom readme by passing the `--readme` parameter or place a `README.md` inside your source folder.
+You can set the title by passing it to the `sidebarTree('Mainpage title')` function.
+
 ## @vuepress comment block
 
 You can add custom meta data to your pages
@@ -108,13 +114,12 @@ Simply add:
 /*
  * @vuepress
  * ---
- * title: You Custom Title
+ * title: Your custom title
  * ---
  */
 ```
 
-More inromation: https://vuepress.vuejs.org/guide/markdown.html#front-matter
-
+More information: https://vuepress.vuejs.org/guide/markdown.html#front-matter
 
 ## Example
 
@@ -128,17 +133,11 @@ yarn
 vuepress-jsdoc
 
 # Generate docs
-yarn run docs
+yarn docs
 
 # Run dev server
-yarn run dev
+yarn dev
 
 # Generate dist folder
-yarn run build
-```
-
-## ToDo
-
-- [ ] Update description README.md
-- [ ] Custom README.md
-- [x] Custom meta data
+yarn build
+```
diff --git a/cmds/generate.js b/cmds/generate.js
@@ -22,6 +22,7 @@ function generate(argv) {
   const codeFolder = argv.folder;
   const docsFolder = `${argv.dist}/${codeFolder}`;
   const title = argv.title;
+  const readme = argv.readme;
 
   // remove docs folder
   rimraf(docsFolder, () =>
@@ -32,12 +33,26 @@ function generate(argv) {
 
       await fs.writeFile(
         `${docsFolder}/config.js`,
-        `exports.fileTree=${JSON.stringify(fileTree, null, 4)};
-  exports.sidebarTree=${JSON.stringify(vueSidebar({ fileTree, codeFolder, title }), null, 4)};`
+        `exports.fileTree=${JSON.stringify(fileTree)};exports.sidebarTree = (title = 'Mainpage') => (${JSON.stringify(
+          vueSidebar({
+            fileTree,
+            codeFolder,
+            title
+          })
+        ).replace('::vuepress-jsdoc-title::', '"+title+"')});`
       );
 
       // create README.md
-      await fs.writeFile(`${docsFolder}/README.md`, `Welcome`);
+      let readMeContent = 'Welcome';
+      let readmePath = readme || `${srcFolder}/README.md`;
+
+      try {
+        readMeContent = await fs.readFile(readmePath, 'utf-8');
+      } catch (e) {
+        console.log('INFO: There is no custom readme file.');
+      }
+
+      await fs.writeFile(`${docsFolder}/README.md`, readMeContent);
     })
   );
 

diff --git a/example/documentation/.vuepress/config.js b/example/documentation/.vuepress/config.js
@@ -22,7 +22,7 @@ module.exports = {
         ],
         // Add the generated sidebar
         sidebar: {
-          ...sidebarTree
+          ...sidebarTree('Test')
         }
       }
     }

diff --git a/example/documentation/code/README.md b/example/documentation/code/README.md
@@ -1 +1,9 @@
-Welcome
+# Home
+
+## Section 1
+
+Section 1
+
+## Section 2
+
+Section 2
diff --git a/example/documentation/code/class.md b/example/documentation/code/class.md
@@ -1,9 +1,10 @@
 ---
-title: My Test Class
+title: test class
 ---
 <a name="Test"></a>
 
-## Test**Kind**: global class  
+## Test
+**Kind**: global class  
 
 * [Test](#Test)
     * [new Test()](#new_Test_new)
@@ -17,30 +18,36 @@ title: My Test Class
 
 <a name="new_Test_new"></a>
 
-### new Test()This is a test class
+### new Test()
+This is a test class
 
 <a name="Test+name"></a>
 
-### test.nameSet current name
+### test.name
+Set current name
 
 **Kind**: instance property of [<code>Test</code>](#Test)  
 <a name="Test+name"></a>
 
-### test.nameGet current name
+### test.name
+Get current name
 
 **Kind**: instance property of [<code>Test</code>](#Test)  
 <a name="Test+generateFullName"></a>
 
-### test.generateFullName() ⇒Generate a fullname
+### test.generateFullName() ⇒
+Generate a fullname
 
 **Kind**: instance method of [<code>Test</code>](#Test)  
 **Returns**: an string  
 <a name="Test.Test"></a>
 
-### Test.Test**Kind**: static class of [<code>Test</code>](#Test)  
+### Test.Test
+**Kind**: static class of [<code>Test</code>](#Test)  
 <a name="new_Test.Test_new"></a>
 
-#### new Test([name])Creates an instance of Test.
+#### new Test([name])
+Creates an instance of Test.
 
 
 | Param | Type | Default |

diff --git a/example/documentation/code/config.js b/example/documentation/code/config.js
@@ -1,91 +1,30 @@
-exports.fileTree=[
-    {
-        "name": "class",
-        "path": "/class",
-        "fullPath": "./documentation/code/class"
-    },
-    {
-        "name": "lib",
-        "children": [
-            {
-                "name": "dmd-options",
-                "path": "/dmd-options",
-                "fullPath": "lib/dmd-options"
-            },
-            {
-                "name": "jsdoc-to-markdown",
-                "path": "/jsdoc-to-markdown",
-                "fullPath": "lib/jsdoc-to-markdown"
-            }
-        ]
-    },
-    {
-        "name": "methods",
-        "path": "/methods",
-        "fullPath": "./documentation/code/methods"
-    },
-    {
-        "name": "objects",
-        "path": "/objects",
-        "fullPath": "./documentation/code/objects"
-    },
-    {
-        "name": "subfolder",
-        "children": [
-            {
-                "name": "subfolder.1",
-                "children": [
-                    {
-                        "name": "variables",
-                        "path": "/variables",
-                        "fullPath": "subfolder/subfolder.1/variables"
-                    }
-                ]
-            },
-            {
-                "name": "variables",
-                "path": "/variables",
-                "fullPath": "subfolder/variables"
-            }
-        ]
-    },
-    {
-        "name": "test",
-        "path": "/test",
-        "fullPath": "./documentation/code/test"
-    }
-];
-exports.sidebarTree={
-    "/code/": [
-        {
-            "title": "API",
-            "collapsable": false,
-            "children": [
-                [
-                    "",
-                    "Mainpage"
-                ],
-                "class",
-                "methods",
-                "objects",
-                "test"
-            ]
-        },
-        {
-            "title": "lib",
-            "collapsable": false,
-            "children": [
-                "lib/dmd-options",
-                "lib/jsdoc-to-markdown"
-            ]
-        },
-        {
-            "title": "subfolder",
-            "collapsable": false,
-            "children": [
-                "subfolder/subfolder.1/variables",
-                "subfolder/variables"
-            ]
-        }
+exports.fileTree = [
+  { name: 'class', path: '/class', fullPath: './documentation/code/class' },
+  {
+    name: 'lib',
+    children: [
+      { name: 'dmd-options', path: '/dmd-options', fullPath: 'lib/dmd-options' },
+      { name: 'jsdoc-to-markdown', path: '/jsdoc-to-markdown', fullPath: 'lib/jsdoc-to-markdown' }
+    ]
+  },
+  { name: 'methods', path: '/methods', fullPath: './documentation/code/methods' },
+  { name: 'objects', path: '/objects', fullPath: './documentation/code/objects' },
+  {
+    name: 'subfolder',
+    children: [
+      {
+        name: 'subfolder.1',
+        children: [{ name: 'variables', path: '/variables', fullPath: 'subfolder/subfolder.1/variables' }]
+      },
+      { name: 'variables', path: '/variables', fullPath: 'subfolder/variables' }
     ]
-};
+  },
+  { name: 'test', path: '/test', fullPath: './documentation/code/test' }
+];
+exports.sidebarTree = (title = 'Mainpage') => ({
+  '/code/': [
+    { title: 'API', collapsable: false, children: [['', '' + title + ''], 'class', 'methods', 'objects', 'test'] },
+    { title: 'lib', collapsable: false, children: ['lib/dmd-options', 'lib/jsdoc-to-markdown'] },
+    { title: 'subfolder', collapsable: false, children: ['subfolder/subfolder.1/variables', 'subfolder/variables'] }
+  ]
+});
diff --git a/example/documentation/code/lib/dmd-options.md b/example/documentation/code/lib/dmd-options.md
@@ -3,4 +3,5 @@ title: dmd-options
 ---
 <a name="DmdOptions"></a>
 
-## DmdOptions**Kind**: global class  
+## DmdOptions
+**Kind**: global class