@lamnhan/docsuper v0.0.2

@lamnhan/docsuper

Document generator for Typescript projects.

Table of content

• Introduction
  • What is it?
  • What the benefits?
  • The workflow
• Getting started
  • The CLI
  • The library
  • Understand the source code
  • Configuration
  • Rendering input
  • Using templates
  • Custom sections
• Options
  • Options properties
• Main service
  • Main properties
  • Main methods
    • convert(declaration, output, options?)
    • generateDocs()
    • output(path, rendering)
    • outputLocal()
    • parse(input?)
    • render(rendering, currentContent?, html?)
    • renderLocal()
• Declaration
  • Declaration properties
  • Declaration methods
    • getChild(name)
    • getChildId(childName)
    • getClasses(offset?)
    • getFunctionsOrMethods(offset?)
    • getInterfaces(offset?)
    • getVariablesOrProperties(offset?)
    • hasClasses()
    • hasFunctionsOrMethods()
    • hasInterfaces()
    • hasVariablesOrProperties()
    • isKind(kindString)
    • setId(id)
    • setLevel(level)
• The Parser
  • ParseService methods
    • parse(input?)
• The Converter
  • ConvertService methods
    • convert(declaration, output, options?)
• The Renderer
  • RenderService methods
    • getData(rendering)
    • getDataBatch(batchRendering)
    • render(rendering, currentContent?, html?)
    • renderBatch(batchRendering, batchCurrentContent?)
• Detail API reference

Introduction

Documentation is a crucial part of every great open-source projects. But making docs is such a Pain-In-The-Brain process.

Since Typescript is an self documenting language, we can leverage its power to extract the source code information. This library is based on Typedoc, one of the best tool for generating Typescript documentation.

What is it?

docsuper is a tool for generating documentation directly from the source code.

It provides 3 main services:

• The Parser: turns the source into a Declaration.
• The Converter: converts a Declaration into content data.
• The Renderer: renders the content data to the final content.

Using the CLI, you can easily generate a document by providing the configuration in package.json or docsuper.config.js file.

An example configuration:

{
  "files": {
    "README.md": {
      "head": true,
      "toc": true,
      "section1": ["Class1"],
      "section2": ["Interface2"],
      "license": true
    }
  }
}

Run docsuper generate will output:

• The docs/ folder: the detail document, generated by Typedoc.
• And every document files based on the configuration.

NOTE: docsuper uses Typedoc to generate the detail documentation (can be ignored). The CLI is only used to generate simpler additional document files, such as README.md.

What the benefits?

• Easy to config & usage
• Avoid reference mistakes and code duplications
• Improve source code quality with TSdoc
• Save time and avoid brain damage

The workflow

Adding docsuper to any project in less than 5 simple steps:

1. Coding as usual
2. (Optional) Documenting the source code with TSdoc
3. (Optional) Putting custom sections and placeholders to files
4. Add configuration to package.json or docsuper.config.js
5. Run docsuper generate to generate content

Getting started

You can use docsuper to generate documentation from the command-line interface or manually parsing, converting or rendering content in a Node application.

The CLI

Install globally by running:

npm install -g @lamnhan/docsuper

A command now available from the terminal, you can run: docsuper.

If you wish to run the CLI locally, install the package with --save-dev flag:

npm install --save-dev @lamnhan/docsuper

Then put a script in the package.json, so you can do npm run docs every build.

{
  "scripts": {
    "docs": "docsuper generate"
  }
}

The library

Install as dev dependency:

npm install --save-dev @lamnhan/docsuper

Use the library:

import { docsuper } from "@lamnhan/docsuper";

// init an instance
const generator = docsuper(/* Options */);

// parsing
const parsing = generator.parse("Main");

// rendering
const rendering = generator.render({
  section1: ["Options"],
  section2: ["Main"]
});

See Main for service detail and Options for more options.

Understand the source code

A Typescript project source code contains many elements with different kinds: Variable/Property, Function/Method, Interface, Class, ...

Imagine your source code has 3 files: file1.ts, file2.ts, file3.ts. Each file exports certain elements.

But you can see your whole source code as a single flattened file like this:

// ================== file1.ts ==================

/**
 * This is a Variable element named `PI`
 */
export const PI = 3.14;

// ================== file2.ts ==================

/**
 * This is a Function element named `doSomething`
 */
export function doSomething() {
  return true;
}

// ================== file3.ts ==================

/**
 * This is an Interface element named `Options`
 *
 * And this is the `Options` element detail.
 *
 * Supports Markdown content.
 */
export interface Options {
  /**
   * This is a Property element named `prop1`
   */
  prop1?: string;
  prop2?: number;
}

/**
 * This is a Class element named `Main`
 *
 * And this is the `Main` element detail.
 *
 * Supports Markdown content.
 */
export class Main {
  property = "a property";
  constructor() {}
  /**
   * This is a Method element named `method1`
   */
  method1() {
    return "a method";
  }
}

To get information, we turn any element of the source code into a Declaration (a source code unit). There are 2 types of Declaration:

• Direct: for top level elements, such as: Variable, Function, Interface, Class and a Collection of any top level elements.
• Indirect: for child elements of a top level element, such as: Property and Method.

Configuration

The CLI load configuration from package.json or docsuper.config.js. See Options section for detail.

Open package.json and add:

{
  "name": "my-package",
  "description": "My package description.",
  "@lamnhan/docsuper": {
    "files": {
      "TEST.md": {
        "head": true,
        "s1": ["Main", "SELF"]
      }
    }
  }
}

With the configuration above, you tell the CLI to create a file named TEST.md with two sections:

• The head section: a built-in section that display the package name and description.
• The s1 section: a rendering section that display the source code element title and description.

The TEST.md content would be:

<\section id="head">

\# my-package

**My package description.**

</\section>

</\section id="s1">

\## The `Main` class

**This is a Class element named `Main`**

And this is the `Main` element detail.

Supports Markdown content.

</\section>

Rendering input

Take a look at the s1 section configuration above. We see it holds an array of values: ["Main", "SELF"]. This array is called a rendering input.

A rendering input provide instructions for the Parser and the Converter, it has 3 parts:

• The WHAT: tells the Parser to parse what source code element:
  • Top level elements: provide the name of the element, example: PI, Options, ...
  • Child elements: put a . between the parent and the child name, example: Options.prop1, Main.method1, ...
  • Collection of elements: the list of paths, @ for ./src/ and separated by +, example: @file1.ts+@lib/filex.ts
• The HOW (optional, default to SELF): tells the Converter how we want to extract the information from the parsing result.
• The options (optional): custom converter options, see ConverterOptions.

See the Parser for parsing detail and the Converter for converting detail.

Using templates

Rendering template is a convinient way to render documents for common source code structure. To use a template, just replace rendering sections with the template name:

{
  "files": {
    "TEST.md": "mini"
  }
}

Currently supported 2 templates:

• mini template, included these sections:

  • head: package name & description
  • toc: table of content
  • options: summary properties of Options interface
  • main: full Main class info
  • license: license informatiion

• full template, included these sections:

  • head: package name & description
  • toc: table of content
  • functions: full list of all functions
  • interfaces: summary list of all interfaces
  • classes: full list of all classes
  • license: license informatiion

Custom sections

You can add any custom sections to a document file. The CLI will replace any section exists in the configuration with generated content and keep others as is.

You must wrap content inside the HTML section tag with a unique id.

<\section id="xxx">

Any markdown content goes here!

</\section>

Section can also be put in the source file, called local section.

IMPORTANT: If the content has these structures, you must escape them to avoid conflicts:

• <\section id="xxx">...</\section> (HTML sections with an id)
• \# A heading (Markdown headings, but not intended to be headings)
• <\h1>A heading</\h1> (HTML headings, but not intended to be headings)

Custom generator options

Options can be provided in 3 ways:

• Under the @lamnhan/autodocs property of package.json file
• The docsuper.config.js file for more advanced config
• By the options param when init new docsuper(options?) instance.

The Main service

Convert a declaration into content blocks.

Parameters

Returns

HeadingBlock | TextBlock | ListBlock | TableBlock[]

Generate the API reference using Typedoc.

The default folder is /docs. You can change the output folder by providing the out property of Options.

Returns

void

Render and save a document

Parameters

Returns

void

Render and save documents based on local configuration.

Returns

void

Turn the source code into a Declaration.

Parameters

Returns

Declaration

Render content based on configuration.

Parameters

Returns

string

Render content based on local configuration.

Returns

BatchRenderResult

A Declaration is an object the holds information of a source code element.

The getChild call signature.

Parameters

Returns

Declaration

The getChildId call signature.

Parameters

Returns

string

The getClasses call signature.

Parameters

Returns

Declaration[]

The getFunctionsOrMethods call signature.

Parameters

Returns

Declaration[]

The getInterfaces call signature.

Parameters

Returns

Declaration[]

The getVariablesOrProperties call signature.

Parameters

Returns

Declaration[]

The hasClasses call signature.

Returns

boolean

The hasFunctionsOrMethods call signature.

Returns

boolean

The hasInterfaces call signature.

Returns

boolean

The hasVariablesOrProperties call signature.

Returns

boolean

The isKind call signature.

Parameters

Returns

boolean

The setId call signature.

Parameters

Returns

this

The setLevel call signature.

Parameters

Returns

this

The Parser turns source code into Declaration

The parse call signature.

Parameters

Returns

Declaration

The Converter turns Declaration into content blocks

Converter output

A Declaration supports certain output depended on its kind:

Provide options with the third item of a rendering input:

• Declaration level/id: { level: number, id }
• SELF header: { title, link }
• Raw object: { raw: true }
• Use the default heading: { heading: true }
• Use local anchors (instead of detail links): { local: true }

The convert call signature.

Parameters

Returns

HeadingBlock | TextBlock | ListBlock | TableBlock[]

The Renderer turns a rendering input into the final content

Builtin sections:

• head: Package name & description
• toc: Table of content
• tocx: Table of content, with detail API reference link
• license: License information

The getData call signature.

Parameters

Returns

RenderingData

The getDataBatch call signature.

Parameters

Returns

BatchRenderingData

The render call signature.

Parameters

Returns

string

The renderBatch call signature.

Parameters

Returns

BatchRenderResult

License

@lamnhan/docsuper is released under the MIT license.

⚡️ This document is generated automatically using @lamnhan/docsuper.