#62 - xt-docs: change default template and explain alternatives

config/docs.json

@@ -16,31 +16,16 @@
     "plugins/markdown"
   ],
   "templates": {
-    "footer": "",
-    "copyright": "",
-    "includeDate": "true",
-    "dateFormat": "MMM YYYY",
-    "inlineNav": "true",
-    "inverseNav": "false",
-    "linenums": "true",
-    "showTableOfContents": "true",
-    "showAccessFilter": "true",
-    "collapseSymbols": "true",
-    "methodHeadingReturns": "false",
-    "outputSourceFiles": "true",
-    "outputSourcePath": "true",
-    "search": "true",
-    "stylesheets": [
-      "data:text/css;base64,Zm9vdGVyewogICAgZGlzcGxheTpub25lIWltcG9ydGFudDsKfQ=="
-    ],
-    "scripts": [],
-    "favicon": "./assets/img/128x128.png"
+    "default": {
+      "cleverLinks": true,
+      "monospaceLinks": false
+    }
   },
   "opts": {
     "destination": "./public/documentation",
     "encoding": "utf8",
     "private": true,
     "recurse": true,
-    "template": "./node_modules/foodoc/template"
+    "template": "templates/default"
   }
 }

guide/05-xt-docs-templates.md

@@ -0,0 +1,178 @@
+# Documentation Templates
+
+* * *
+
+<p class='page-intro'>Use templates to customize the look and feel of 
+source code documentation.</p>
+
+* * *
+
+Extension CLI uses [JsDoc](https://jsdoc.app) to document extension projects.
+You can then apply templates to customize the look and feel of these docs.
+
+## Customizing Default Template
+
+If you are using the default template see: [Configuring JSDoc's default template](https://jsdoc.app/about-configuring-default-template.html).
+
+<a href="https://jsdoc.app/about-configuring-default-template.html" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/jsdoc-default.jpg" alt="default template"/>
+</a>
+
+## Alternative Templates
+
+To use an alternative template:
+
+1. Choose a suitable template and use npm to install it at project level
+2. In the [documentation configuration](/05-xt-docs/#default-configuration):
+    1. Specify `"opts.template"` to indicate which template to use    
+    2. Customize the template options under `"templates"` 
+
+* * *
+
+### Braintree JSDoc Template
+
+[Source and configuration](https://github.com/braintree/jsdoc-template)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/braintree/jsdoc-template)
+
+<a href="https://github.com/braintree/jsdoc-template" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/braintree.jpg" alt="braintree"/>
+</a>
+
+* * *
+
+### clean-jsdoc-theme
+
+[Source and configuration](https://github.com/ankitskvmdam/clean-jsdoc-theme)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/ankitskvmdam/clean-jsdoc-theme)
+
+_Light mode_
+
+<a href="https://github.com/ankitskvmdam/clean-jsdoc-theme" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/clean-jsdoc-light.jpg" alt="light mode"/>
+</a>
+
+_Dark mode_
+
+<a href="https://github.com/ankitskvmdam/clean-jsdoc-theme" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/clean-jsdoc-dark.jpg" alt="dark mode"/>
+</a>
+
+* * *
+
+### Foodoc
+
+[Source and configuration](https://github.com/steveush/foodoc)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/steveush/foodoc)
+
+
+<a href="https://github.com/steveush/foodoc" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/foodoc.jpg" alt="foodoc"/>
+</a>
+
+* * *
+
+### JsDoc Template
+
+[Source and configuration](https://github.com/AlexisPuga/jsdoc-template)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/AlexisPuga/jsdoc-template)
+
+<a href="https://github.com/AlexisPuga/jsdoc-template" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/jsdoc-template.jpg" alt="JsDoc Template"/>
+</a>
+
+* * *
+
+### Tidy JsDoc
+
+[Source and configuration](https://github.com/julie-ng/tidy-jsdoc)
+
+![GitHub last commit](https://img.shields.io/github/last-commit/julie-ng/tidy-jsdoc)
+
+<a href="https://github.com/julie-ng/tidy-jsdoc" 
+   class="preview" target="_blank" rel="noreferrer nofollow">
+  <span class="bar">
+      <span class="red"></span>
+      <span class="yellow"></span>
+      <span class="green"></span>
+  </span><img src="/assets/images/tidy-jsdoc.jpg" alt="Tidy JsDoc"/>
+</a>
+
+* * *
+
+<!-- style the preview views -->
+<style>
+article a.preview {
+  display: block;
+  margin: 2rem auto;
+  width:1000px; max-width: calc(100% - 42px); 
+  box-shadow: 0 12px 42px rgba(0,0,0,.22), 0 4px 6px rgba(0,0,0,0.4);
+  border-radius: 4px;
+  overflow: hidden;
+  position: relative;
+}
+article a.preview img{
+  width: 100%;
+  background: #222;
+  display: block;
+  position: relative;
+  margin:0;
+}
+article a.preview .bar{
+  padding:10px 12px; width:100%;
+  background: #e4e4e4;
+  position: relative;
+  display: flex;
+  flex-direction: row;
+  justify-content: flex-start;
+  margin:0;
+}
+article a.preview .bar > span{
+  height: 10px; width:10px;
+  border-radius: 50%;
+  background: #9997;
+  margin-right: 8px;
+}
+article a.preview .bar .red{
+    background:#FF5952;
+}
+article a.preview .bar .yellow{
+    background:#E6C029;
+}
+article a.preview .bar .green{
+    background:#54C22B;
+}
+</style>

guide/05-xt-docs.md

@@ -12,10 +12,6 @@ generate documentation for javascript files in an extension project. JSDoc is
 a flexible documentation generator that converts javascript code comments to 
 readable HTML/CSS files which you can be hosted for example with github pages.
 
-You can use any compatible template of choice to skin your docs. Learn [more 
-about templating here](#templates).
-
-
 ## Commands
 
 Braces `{ }` indicate that the user must choose one (and only one) of the 
@@ -72,91 +68,45 @@ If these two locations cause a conflict, alternatively you can provide a path
 to configuration file with `-c` (`--config`) flag, followed by path to file. 
 [See commands for an example](#commands).
 
-
-### Minimum Project-Level Configuration
-
-Within the extension project you should define, at minimum, the following 
-configuration options:
-
-```json
-"xtdocs": {
-  "templates": {
-    "systemName": "{extension name}",
-    "systemSummary": "{short description}",
-    "systemColor": "{css-color}"
-  }
-}
-```
-
-where:
-
-| key | Description of value |
-| --- | --- |
-| `systemName`| Project name |
-| `systemSummary` | Short description of your project; becomes a subheading in generated docs |
-| `systemColor` | Theme color, e.g. hex or rgb value `#000000`.
+You can use any compatible template of choice to style your docs. You can find 
+some [templating options here](05-xt-docs-templates.md).
 
 ### Default Configuration
 
 The CLI uses a documentation configuration file shown below. You can override any of these key-value pairs at project level. You can also add key-value pairs that are not defined here so long as they follow to [JSDoc guidelines](https://jsdoc.app/about-configuring-jsdoc.html).
 
 ```json
 "xtdocs": {
-  "tags": {
-    "allowUnknownTags": true,
-    "dictionaries": [
-      "jsdoc"
-    ]
-  },
-  "source": {
-    "include": [
-      "src"
-    ],
-    "includePattern": ".js$",
-    "excludePattern": "(node_modules/|docs)"
-  },
-  "plugins": [
-    "plugins/markdown"
-  ],
-  "templates": {
-    "footer": "",
-    "copyright": "",
-    "includeDate": "true",
-    "dateFormat": "MMM YYYY",
-    "inlineNav": "true",
-    "inverseNav": "false",
-    "linenums": "true",
-    "showTableOfContents": "true",
-    "showAccessFilter": "true",
-    "collapseSymbols": "true",
-    "methodHeadingReturns": "false",
-    "outputSourceFiles": "true",
-    "outputSourcePath": "true",
-    "search": "true",
-    "stylesheets": [
-      "data:text/css;base64,Zm9vdGVyewogICAgZGlzcGxheTpub25lIWltcG9ydGFudDsKfQ=="
+    "tags": {
+      "allowUnknownTags": true,
+      "dictionaries": [
+        "jsdoc"
+      ]
+    },
+    "source": {
+      "include": [
+        "src"
+      ],
+      "includePattern": ".js$",
+      "excludePattern": "(node_modules/)"
+    },
+    "plugins": [
+      "plugins/markdown"
     ],
-    "scripts": [],
-    "favicon": "./assets/img/128x128.png"
-  },
-  "opts": {
-    "destination": "./public/documentation",
-    "encoding": "utf8",
-    "private": true,
-    "recurse": true,
-    "template": "./node_modules/foodoc/template"
+    "templates": {
+      "default": {
+        "cleverLinks": true,
+        "monospaceLinks": false
+      }
+    },
+    "opts": {
+      "destination": "./public/documentation",
+      "encoding": "utf8",
+      "private": true,
+      "recurse": true,
+      "template": "templates/default"
+    }
   }
 }
 ```
 
-## Templates
-
-`templates` key is used specifically to customize the options for a template of choice. This is useful if you want to change the look and feel of the generated documentation. The default template used by this CLI is 
-[Foodoc](https://github.com/steveush/foodoc#configuring-the-template). 
-
-You can change the template by overriding `opts.template` in the project-level configuration, and by adding the template package of your choice to project-level dependencies.
-
-[This list](https://cancerberosgx.github.io/jsdoc-templates-demo/demo/) can help you get started with picking a custom template. If you cannot find one that you like, you can always make and publish your own.
-
-
-

guide/assets/custom.css

@@ -16,7 +16,10 @@ table tr th :last-child, table tr td :last-child {margin-bottom: 0; }
     box-shadow: none;
     background: var(--md-code-bg-color);
 }
-.md-typeset table:not([class]) code{
+.md-typeset code{
+    padding: 3px .35em;
+}
+.md-typeset table:not([class]) code {
     font-size: .70rem;
 }
 .md-typeset table:not([class]) tr:hover{

mkdocs.yml

@@ -23,7 +23,9 @@ nav:
       - Static assets: 03-xt-build-assets.md
       - Commands: 03-xt-build-cmds.md
     - 'xt-clean': 04-xt-clean.md
-    - 'xt-docs': 05-xt-docs.md
+    - 'xt-docs':
+      - Configuration: 05-xt-docs.md
+      - Templates: 05-xt-docs-templates.md
     - 'xt-sync': 06-xt-sync.md
     - 'xt-test': 07-xt-test.md
     - 'extension-cli': 08-xt-create.md

package.json

@@ -66,7 +66,6 @@
     "cross-env": "^7.0.3",
     "del": "^6.0.0",
     "eslint": "^7.29.0",
-    "foodoc": "^0.0.9",
     "globby": "^11.0.4",
     "gulp": "^4.0.2",
     "gulp-change": "^1.0.2",