Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Is it possible to generate single page doc html with TypeDoc for TypeScript project?

Let's say I have two TypeScript classes in my library called SuperBase. The Databaseand the Record.

Would it be possible with TypeDoc to generate a single page with something like very simple format below. It doesn't have to be exactly that way, just something simple and similar.

It should be very simple and minimal, and just one page. Something like you would write yourself in a Markdown readme. All it needs to do just fetch those docs from sources and glue it into the single HTML page. Is that possible with TypeDoc or maybe with some other tool for TypeScript?

(header) SuperBase
(text) description of the package taken from package.json or somewhere else

(header) Database
(text) Description of the database taken from class docs

(subheader) connect(url: string)
(text) description of the connect method taken from method docs

(header) Record
(text) Description of the Record taken from class docs

(subheader) validate()
(text) description of the validate method taken from method docs
like image 437
Alex Craft Avatar asked Jul 07 '19 00:07

Alex Craft


1 Answers

You can use typedoc, typedoc-plugin-markdown, showdown and concat-md in a single command. In result, you both have a single page Markdown and HTML together.

(Disclaimer: I am developer of open source concat-md and readmeasy)

How

typedoc-plugin-markdown produces a series of Markdown files from your TypeDoc comments and concat-md creates a single file from multiple Markdown files.

In case you need further customize README.md file in addition to including created API Markdown file, you can use a README.hbs or README.njk template with readmeasy and include created API Markdown into your customized README.md.

Example

Single Command

Below command creates multiple files into a temp directory merge them to README.md file and deletes temp directory. (rimraf module is used for delete, because it is cross OS compatible)

$ npm install -D typedoc typedoc-plugin-markdown concat-md rimraf showdown
$ rimraf temp-docs && typedoc --plugin typedoc-plugin-markdown --theme markdown --mode file --out temp-docs && concat-md --toc --decrease-title-levels --dir-name-as-title temp-docs > README.md && showdown makehtml -i README.md -o README.html && rimraf temp-docs

Description

  • Install necessary modules:
$ npm install -D typedoc typedoc-plugin-markdown concat-md showdown
  • Create Markdown files using TypeDoc comments into temp-docs directory:
$ typedoc --plugin typedoc-plugin-markdown --theme markdown --mode file --out temp-docs
  • Create a single README.md Markdown file from them: (Also creates table of contents, adds directory names as titles, and decreases title levels automatically)
$ concat-md --toc --decrease-title-levels --dir-name-as-title temp-docs > README.md
  • Convert created Markdown into HTML using any converter: (I used showdown for this example)
$ showdown makehtml -i README.md -o README.html
like image 108
ozm Avatar answered Nov 06 '22 13:11

ozm