Giter VIP home page Giter VIP logo

tidy-jsdoc's Introduction

tidy-jsdoc

Build Status Known Vulnerabilities

A minimalist and clean jsdoc template.

Features

Preview

Note Latest Version 1.0 is considered a breaking change because the design changes significantly.

Examples

Version 1.0 - Preview

Based on the default jsdoc template and inspired in design by vue.js documentation and docsify.

Looking for the old design?

If you want keep the old design, version your package.json appropriately. Preview old designs in the images folder.

Note: the old designs ^0.3.0 will not be updated or maintained.

Usage

Add Dependency

To use this jsdoc template in a project, first install the packages:

npm install --save-dev jsdoc tidy-jsdoc

Generate Docs

Once you've configured jsdoc and added syntax to your JavaScript files, you can generate the HTML files like so, optionally including a readme file:

jsdoc --readme README.md -c jsdoc.json

Configure JSDoc

Then configure jsdoc to use the tidy template. Below is an example jsdoc.json configuration file. Be sure to adjust

  • template
    Points to ./node_modules/tidy-jsdoc

  • prism-theme
    Optionally pick a prismjs theme for styling your code. Defaults to "prism-tomorrow-night". Choose from templates available in ./static/styles/vendor/ folder

  • destination
    Output is ./docs/, allowing for easy GitHub Pages publishing.

  • metadata
    Customize title, logo, etc.

  • styles
    Let's your customize colors, etc. See details below.

{
  "tags": {
    "allowUnknownTags": true,
    "dictionaries": [
      "jsdoc",
      "closure"
    ]
  },
  "source": {
    "include": [
      "src"
    ],
    "includePattern": ".+\\.js(doc)?$",
    "excludePattern": "(^|\\/|\\\\)_"
  },
  "opts": {
    "template": "./node_modules/tidy-jsdoc",
    "prism-theme": "prism-custom",
    "encoding": "utf8",
    "destination": "./docs/",
    "recurse": true
  },
  "plugins": [
    "plugins/markdown",
    "plugins/summarize"
  ],
  "templates": {
    "cleverLinks": false,
    "monospaceLinks": false
  },
  "metadata": {
    "title": "My JavaScript Library",
  }
}

Customize the Template

Adjusting Theme with CSS variables

As of version 1.0, this template is styled via css variabbles, so you can adjust it to your brand. Inside your jsdoc.json configuration file, add an addional styles property, for example:

{
  "metadata": "...",
  "styles": {
    "text-color": "#111",		
    "primary-color": "blue",
    "heading-color": "var(--primary-color)"
  }	
}

This would output in your document <head>:

<style>
  :root {
    --text-color: #111;
    --primary-color: blue;
    --heading-color: var(--primary-color);
  }
<style>

The keys and values are arbitrary, but the CSS should be valid. For a full list of the available variables, see _vars.scss.

Development

For more information about creating jsdoc templates, see the jsdoc GitHub repository.

When editing SCSS, build the CSS automatically like so:

npm run sass:watch

Note: you'll have to commit both the scss and css files.

tidy-jsdoc's People

Contributors

dependabot[bot] avatar gamtiq avatar julie-ng avatar paul-mckay avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar

tidy-jsdoc's Issues

Properties of ES classes not appearing in the output

(sorry to bother you again...)

Using the default template, documenting properties of an ES2015 class is just a matter of adding a @type annotation to each property (whether it's an instance property, an instance getter, or a static getter). Properties appear under the "Members" section.

For the FinderError class in this file:
https://github.com/cedx/which.js/blob/master/lib/finder.js#L137

The default template output is:
Default output

But when using the Tidy template, the "members" section is skipped:
Tidy output

Whatever class property I'm documenting, they never appear in the generated output.
Another example is the static getter Finder.isWindows from the same source file:
https://github.com/cedx/which.js/blob/master/lib/finder.js#L15

It appears in the "Members" section with the default template, but not with the Tidy template.

Better support of type definitions

I prefer to use @typedef for documenting options objects. But currently, the output of type definitions is not very useful: it only displays the @type annotation but not the @property ones.
It would be very cool if @property annotations were also displayed.

Some information missing when compared to the standard JSDOC3 output.

Given the following JavaScript:

const TestClass = class TestClass {
  /**
   * Create a TestClass instance.
   * @class TestClass
   * @classdesc TestClass represents an object of some sort.
   * @author Bob Smith <[email protected]>
   * @param {(number|string)} value - Some value passed in.
   */
  constructor(value) {
    this._ctorValue = this.constructor.validationRegExp.test(value) ? value : 'someDefaultValue';
  }

  /**
   * Returns some arbitrary value given the supplied parameter.
   * @static
   * @param {string} value - A string.
   * @returns {string} Given the following input: "ABC" would return "A".
   */
  static getArbitraryValue(value) {
    return value[0];
  }


  /**
   * Returns a regular expression (RegExp) which indicates a valid TestClass value.
   * @static
   * @readonly
   * @property {regExp} validationRegExp
   */
  static get validationRegExp() {
    return /^\w+$/;
  }

  /**
   * Returns the arbitrary value from a valid TestClass value.
   * @instance
   * @readonly
   * @property {string} arbitraryValue - Given the following input: "ABC" would return "A".
   */
  get arbitraryValue() {
    return this.constructor.getArbitraryValue(this._ctorValue);
  }
};

When running this through the standard JSDOC3 template, compared to the tidy-jsdoc template, some fields appear to be missing. Speficially, the static and readonly descriptors for members / properties. In addition, some of the descriptive text is missing in the members / properties (also links to the source for the members / properties would be nice to have):

standardjsdoc-compared-to-tidy-jsdoc-2020-02-18_1358

My JSDOC config is simple, and that looks like:

  const jsDocConfig = {
    opts: {
      destination: './docs',
      template: '../node_modules/tidy-jsdoc'
    },
    metadata: {
      title: 'Some Example'
    }
  };

relevant package.json:

{
  "jsdoc": "^3.6.3",
  "tidy-jsdoc": "^1.2.2"
}

Is this something which can be solved through a configuration, or would this require a change within tidy-jsdoc?

Support for @hideconstructor

Can you please add support for the @hideconstructor tag?

--- a/tmpl/method.tmpl
+++ b/tmpl/method.tmpl
@@ -19,3 +19,3 @@ var hasMethodSummary = (data.kind !== 'class')
 
-<?js if (data.kind !== 'module') { ?>
+<?js if (data.kind !== 'module' && !data.hideconstructor) { ?>
 
@@ -50,3 +50,3 @@ var hasMethodSummary = (data.kind !== 'class')
 
-<?js if (data.kind !== 'module' && data.description) { ?>
+<?js if (data.kind !== 'module' && data.description && !data.hideconstructor) { ?>
 <div class="method-description">
@@ -76,3 +76,3 @@ var hasMethodSummary = (data.kind !== 'class')
 
-<?js if (data.params && params.length) { ?>
+<?js if (data.params && params.length && !data.hideconstructor) { ?>
     <h4 class="method-heading">Parameters</h4>

Thank you!

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.