Skip to content

Latest commit

 

History

History
266 lines (188 loc) · 18 KB

README.md

File metadata and controls

266 lines (188 loc) · 18 KB
Raw

dmd-readme-api

A jsdoc2md template plugin generating elegant, compact one-page APIs in markdown, suitable for embedding in a README.md.

Installation

npm i --save-dev dmd-readme-api @liquid-labs/jsdoc-to-markdown @liquid-labs/dmd

Though designed as a plugin to the standard jsdoc2md, 'dmd-readme-api 'relies on additional features not present in the baseline tool. Refer to the custom jsdoc2md notes for additional details.

Usage

npx jsdoc2md \
    --configure ./jsdoc.config.json \
    --files 'src/**/*' \
    --global-index-format grouped \
    --name-format \
    --plugin dmd-readme-api \
    --plugin @liquid-labs/dmd \
    --clever-links \
    --no-cache
  • You must specify '@liquid-labs/dmd' as the final plugin. See additional notes in the custom jsdoc2md notes.
  • You must specify --plugin even if it's specified in the jsdoc.config.json See below for further details on plugin and jsdoc.config.json setting and refer to the formatting options section for additional options.
  • The no-cache avoids erroneously using previous renderings even when settings have changed. Rendering is fast enough that it's not really worthwhile to have the cache enabled as it can cause problems.

jsdoc.config.json:

{
    "plugins": [],
    "recurseDepth": 10,
    "source": {
        "includePattern": ".+\\.(c|m)?js(doc|x)?$",
        "excludePattern": "((^|\\/|\\\\)_|.+\\.test\\.(c|m)?jsx?$)"
    },
    "sourceType": "module",
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc","closure"]
    },
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    }
}

Note that jsdoc2md doesn't do anything with this file. It's passed through to jsdoc. Some important notes:

  • jsdoc2md and jsdoc are not fully integrated at this point; the 'plugins' here is ignored by jsdoc2md.
  • You need to tags.allowUnknownTags true or you won't get support for the handy jsdoc2md @category tag (and a few others).
  • If you want to pick up .mjs and .cjs files, you must override source.encludePattern. How this works is that jsdoc2md will read in everything matched by the --files (or "files" in .jsdoc2md.config.json) and then apply the include and exclude patterns defined in jsdoc.config.json.
  • The templates are effectively ignored currently and are shown here with their default values.

Features

Extended syntax:

  • You can @hide or @ignore function parameters in the documentation; see hide parameters.

New options:

  • Adds configurable section title to main output; see the title format option.
  • Adds support for simple list and grouped global identifiers; see the global index format option.

Layout improvements (As compared to the base dmd template):

  • Only display summary (first line) of documentation in the index and show full documentation in the linked entry. (This makes thins a lot more compact.)
  • Added sorting of the underlying data so everything is displayed in a consistent order.
  • Add links to the source code where an identifier is defined; see source links option.
  • Add links from identifier documentation back to the both identifier "kind" and "category" indexes; see index links options.
  • Can suppress the display of 'Category' in identifier documentation. Displaying the category is less important when we have grouped the items already, and this makes the code more compact. See category display and index links options.
  • The name-format option is also effective on parameter names in table layout mode.
  • The name-format option is also effective in class name index links and section headers.
  • Fixes escape issues with the display of 'default values' and displays string values in plain text (rather than monospaced).
  • When the identifer category is displayed, the category label is now a link back to the category index.
  • Fixes HTML style <table>s and uses native Markdown tables instead.
  • Fixes HTML <code> tags and uses Markdown native backtick instead.
  • Uses compact method signatures in any index; much easier to read.
  • Render @throws on one line if only one @throws defined, otherwise generate list.
  • Makes the 'Examples' section more compact.
  • Only display identifier 'kind' when it's complex; otherwise it's obvious based on the section.

Extended syntax

Hide parameters

  • A parameter whose description contains the a @hide or @ignore tag will not be included in documentation.
  • This can be useful for parameters which are intended for use by the code/system.
  • Consider noting such variables somewhere in the documentation (under a 'Common parameters' section at the start of the API documentation for example).

Plain and monospace link tags

Format options

Note, some options can be set via the command line and via .jsdoc2md.json while others can only be set via the .jsdoc2md.json configuration file (placed in the project root).

Title

  • By default, the generated document will have a title 'API reference'.
  • You can override this by setting "title" in the .jsdoc2md.json configuration file (cannot be set via command line options).
  • Setting the "title" option to literal false will suppress the title altogether. This is useful when you have a custom introduction to the API section and you want the API documentation to flow into it. Note that the heading depth is unaffected by this option.

Heading depth

  • The default depth of the title header is '2' (e.g., '##').
  • You can change this by setting heading-depth in the .jsdoc2md.json configuration file or with --heading-depth on the CLI.

Clever and monospace links

  • By default {@link} tags render the link label in plain text. You can use {@linkplain} and {@linkcode} tags to explicitly control rendering.
  • Setting clever-links true will render links pointing to a URL in plain text and all others (which presumably point to internal identifiers such as a function or field) in monospace.
  • Setting monospace-links to true will render all {@link} tags in monospace format. This option is ignored in clever-links is true.
  • You can set clever-links and monospace-links in the .jsdoc2md.json configuration file or use the --clever-links and --monospace-links command line option. (This requires the '@liquid-labs/jsdoc-to-markdown' tool variation; see custom jsdoc2md notes for further details.)

Github flavored markdown

  • By default, dmd generated GitHub flavored markdown.
  • If this is a problem, you can set no-gfm true in the .jsdoc2md.config.json or use the --no-gfm command line option.

Global index format

  • Controls how the display of the global identifiers index. The default index format is dl, which can be pretty bulky.
  • This DMD adds support for grouped and list formats. Other options are dl, table.
  • We recommend the grouped setting, which will organize global identifiers by 'kind' and then @category, if present. If you don't use @category, then grouped is more or less equivalent to list.
  • This option can be set with global-index-format in the .jsdoc2md.json configuration file or with --global-index-format on the CLI.

Member index format

  • Controls how the member identifiers index (of a @module or @namespace for example) is displayed. Default is grouped.
  • May be set using member-index-format in .jsdoc2md.config.js or with --member-index-format on the command line. Can be grouped or list.

Module index format

  • Controls how module identifier indexes are displayed; dl by default.
  • Can be set with module-index-format in the .jsdoc2md.config.json file or with the --module-index-format option on the command line. Supports none, grouped, table, and dl.

Parameter list format

  • Controls how function parameters are displayed; table by default.
  • Can be set with param-list-format in the .jsdoc2md.config.json file or with the --param-list-format option on the CLI. Support table and list.

Category display

  • By default, the category of an identifier is included in the documentation when a {@category} tag has been included in the jsdoc documentation.
  • This can be suppressed by setting the hide-categories option to true.
  • This option can currently only be set in the .jsdoc2md.config.js.

Source links

  • By default, a link to the source where an identifier is implemented is included in the identifier documentation.
  • You can turn suppress these source links by setting hide-source-links to true.
  • This option can currently only be set in the .jsdoc2md.config.js.

Index links

  • By default, links back to the 'kind' indexes (if it exists) is displayed in the identifier documentation.
  • If hide-categories is true, we also display a link back to the identifier category index, if any. (The category label itself is a link if present.)
  • These links can be suppressed by setting the hide-index-links to true.
  • This option can currently only be set in the .jsdoc2md.config.js.

Name format

  • By default, identifier names are rendered in plain case.
  • You almost certainly want to override this and set name-format in the .jsdoc2md.config.json file to true or include the --name-format option on the CLI. This will cause identifier names to render in monospace. (e.g., foo).

Private identifiers

  • Controls the display of identifiers marked @private; by default they are hidden.
  • Can be set with private in .jsdoc2md.config.json (true or false, the default) or with the --private option on the CLI.

Examples

History

We wanted good, compact API documentation and tried a lot of different ways to get there.

Our main goal was to embed an easy to read, automatically generated API in our README.md files.

Our first thought, after some research, was to use Docusaurus, hosted on GitHub. We found this script and, even more promising, this library, which seemed to be exactly what we wanted because Docusaurus supports rendering React components and the script and library promised to generate API documentation as a Docusaurus doc.

Unfortunately, neither worked out. The script has a lot of assumptions and the library just straight up wouldn't work. It loosk like it hasn't been updated since Docusaurus 2.01. Too bad, it's the right idea.

We instead turned to tackling the goals in two steps. The first step was rendering the jsdocs in markdown and appending those to a simple template.

So, the way jsdocs works is gather's all the doc information into JSON data. The data representing the parsed jsdocs is passed through a templating system to generate the output. We tried many different templates, expecting to find one that worked off the shelf.

However after trying many dmd templates,2 we found they were all lacking something we needed (or really wanted). The biggest problem was that none of them handled indexing the methods really well. And we tried all different configurations and setups: using @module and making everything a @memberof the module, creating a @namespace, tricks to create docs by the file (like how Java Docs do it), but nothing came out satisfactorily. The persistent problem was that it was printing the whole description in the index summary, making them difficult to read and entirely redundant.

A little less significant, all the existing templates were using the full method signatures in the index summary too. If the other problem hadn't been dispositive, this also made for clunky reading, though we probably would have lived with it if that was the only problem.

In some of them, the intra-page links didn't work, so those were a no-go. And none of them had really good looking output, in our opinion. May mixed in HTML unecessarily.

But one nice thing about jsdoc2md is it's "relatively" easy to customize. You have to wrap your head around their templating system... and frankly the tag documentation is a bit lacking. It's really not clear when you should use @module, what's the difference between @kind and @type, or what a @namespace is for, etc.. So it took some experimentation and walking through the template to really understand how things were being used because many details in the output of the existing templates were unexpected in a bad way.

So, anyway, there's a template system called dmd which process handlebarjs and jsdoc2md uses, dmd and you can make little template partials to override snippets of their template. So that's what we did, and that's what this library is.

We tried to cleanup a lot of things in template. You can see the full list of modifications in the DEV_NOTES.md. The result is a template that, when used jsdoc2md, creates nice, relatively compact Markdown you can attach right to your README.md.

Custom jsdoc2md notes

'dmd-readme-api' relies on a few features not found in the base implementations 'jsdoc-to-markdown' and 'dmd' implementations. We hope the features are integrated into the baseline tools, but until then, it is necessary to us the '@liquid-labs/jsdoc-to-markdown' and '@liquid-labs/dmd' derivatives.

We've added a number of features necessary to support 'dmd-api-readme'.
  • '@liquid-labs/dmd' adds support for "clever links" and "monospace links" options. Changes submitted to the 'dmd' project in PR #86 and 'jsdoc-to-markdown' in PR #302.
  • '@liquid-labs/dmd' adds support for the {@linkplain} and {@linkcode} tags. Changes also submitted to 'dmd' PR #86.
  • '@liquid-labs/dmd' adds support for grouping globals as well well as children. This is necessary for our grouped global index format option. Changes have been submitted to the 'dmd' project in PR #86.
  • '@liquid-labs/dmd' adds a hasMultipleIdentifiers helper function which is used to determine when some labels can be discarded (thus saving space). These changes have not yet been submitted to the 'dmd' project (waiting on other changes to go through).
  • '@liquid-labs/jsdoc-to-markdown' adds support for --clever-link and --monospace-link CLI options. Submitted to 'jsdoc-to-markdown' in PR #302.
  • '@liquid-labs/jsdoc-to-markdown' removes 'dmd' as a hardcoded require and allows us to plug in our derivative @liquid-labs/dmd variation. Changes will be submitted to 'jsdoc-to-markdown' once other changes have been accepted.

TODOs

  • Support hiding the 'kind' index independently, hide-kind-index-links.
  • Support explicit control over the 'category' index: category-links with possible value always, never, and conditional (current behavior and default).
  • Support navigation-link-style with possible values compact (current behavior and default), subtitle (right under the title), end (at the end of the entry body), and bookend (both under the title and at the end of the entry body).

Contributing

Plase feel free to submit any bug reports or feature suggestions. You're also welcome to submit patches of course. We don't have a full contributors policy yet, but you can post questions on our discord channel. It's not monitored 24/7, but you should hear back from us by next business day generally.

Support and feature requests

The best way to get free support is to submit a ticket. You can also become a patron for as little as $1/month and get priority support and request new feature on all Liquid Labs open source software. You can get these benefits and support our work at patreon.com/liquidlabs.

Footnotes

  1. as of 2024-02-09 ↩

  2. dmd-clean, dmd-bitbucket, npm-clear, and @godaddy/dmd ↩