Autogenerated API Documentation

[yosriady]

Closes #87 and unblocks #86

This PR adds a new npm run docs command to generate API and type documentation for the COMIT JS SDK. The docs command generates HTML in the docs/ directory (gitignored) to be embedded later in the main Docusaurus site.

About

Unfortunately, neither documentation.js and esdoc are compatible with our requirements around handwritten documentation and Typescript - despite repeated attempts at making it work and custom configuration.

The good news is we can get it done with Typedoc.

Getting Started

npm install
npm run docs

Your browser should automatically open the index.html file.

This PR also supports Markdown generation. To generate Markdown instead of HTML, do:

npm run docs:md

Screenshots

Annotating SDK Code

You can see an example annotated file in tokens/tokens.ts. You can use the following tags:

• @description
• @params
• @returns

The above snippet will result in:

Check this out for more information on what tags are supported.

Advanced Configuration

In typedoc.json, you can configure the generation parameters:

{
  "inputFiles": ["./src"],
  "mode": "modules",
  "out": "docs",
  "exclude": "**/*+(index|.spec|.e2e|.d).ts",
  "tsconfig": "./tsconfig.json",
  "includeDeclarations": true,
  "excludeExternals": true,
  "excludeNotExported": false,
  "excludePrivate": true,
  "excludeProtected": false,
  "ignoreCompilerErrors": false,
  "media": "TODO",
  "includes": "TODO, include for literate style documentation",
  "theme": "default",
  "includeVersion": true,
  "readme": "README.md",
  "categorizeByGroup": false,
  "defaultCategory": "Other",
  "hideGenerator": true
}

• theme can be default which is a multi-page HTML project or minimal which is a single HTML file for easy embedding.
• includes allow us to insert snippets of documentation in between the generated HTML for a more 'literate programming' style of documentation

Check this out for details on configuration options.

Next Steps

• (Team) Clone this branch and give feedback on the output.
• (Team) Annotate the rest of the JS SDK.
• (Yos) Embed the HTML on a Docusaurus page.

[mergify]

Are you sure the changelog does not need updating?

[claassistantio]

All committers have signed the CLA.

[yosriady]

Please feel free to share your feedback or ask any questions here.

[da-kami]

gave it a try, like it :)

[D4nte]

Awesome job. I love the links to Github repo.

[yosriady]

Perfect. I'll proceed with embedding this API doc on the https://comit.network Docusaurus site.