README
@lamnhan/docsuper
Document generator for Typescript projects.
Table of content
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:
- Coding as usual
- (Optional) Documenting the source code with TSdoc
- (Optional) Putting custom sections and placeholders to files
- Add configuration to
package.json
ordocsuper.config.js
- 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 aCollection
of any top level elements. - Indirect: for child elements of a top level element, such as:
Property
andMethod
.
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
- Top level elements: provide the name of the element, example:
- 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)
Options
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 newdocsuper(options?)
instance.
Options properties
Name | Type | Description |
---|---|---|
apiGenerator | "typedoc" | "none" |
Detail API generator |
apiUrl | string |
Custom API reference url, default to the Github Pages repo url |
converts | AdditionalConverts |
Additional converts |
files | object |
List of documents to be generated: key is the path to the document and value is a template name or a rendering input |
noAttr | boolean |
No generator footer attribution |
typedoc | TypedocConfigs |
Custom Typedoc config |
Main service
The Main service
Main properties
Name | Type | Description |
---|---|---|
Content | ContentService |
Get the Content service |
Converter | ConvertService |
Get the Converter service |
Loader | LoadService |
Get the Loader service |
Parser | ParseService |
Get the Parser service |
Project | ProjectService |
Get the Project service |
Renderer | RenderService |
Get the Renderer service |
Typedoc | TypedocService |
Get the Typedoc service |
Main methods
Function | Returns type | Description |
---|---|---|
convert(declaration, output, options?) | HeadingBlock | TextBlock | ListBlock | TableBlock[] |
Convert a declaration into content blocks. |
generateDocs() | void |
Generate the API reference using Typedoc. |
output(path, rendering) | void |
Render and save a document |
outputLocal() | void |
Render and save documents based on local configuration. |
parse(input?) | Declaration |
Turn the source code into a Declaration. |
render(rendering, currentContent?, html?) | string |
Render content based on configuration. |
renderLocal() | BatchRenderResult |
Render content based on local configuration. |
convert(declaration, output, options?)
convert(declaration, output, options?)
Convert a declaration into content blocks.
Parameters
Param | Type | Description |
---|---|---|
declaration | Declaration |
The declaration |
output | string |
Expected output |
options | ConvertOptions |
Custom convertion options |
Returns
HeadingBlock | TextBlock | ListBlock | TableBlock[]
generateDocs()
generateDocs()
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
output(path, rendering)
output(path, rendering)
Render and save a document
Parameters
Param | Type | Description |
---|---|---|
path | string |
Path to the document |
rendering | Rendering |
Rendering configuration |
Returns
void
outputLocal()
outputLocal()
Render and save documents based on local configuration.
Returns
void
parse(input?)
parse(input?)
Turn the source code into a Declaration.
Parameters
Param | Type | Description |
---|---|---|
input | string |
Parsing input |
Returns
render(rendering, currentContent?, html?)
render(rendering, currentContent?, html?)
Render content based on configuration.
Parameters
Param | Type | Description |
---|---|---|
rendering | Rendering |
Redering configuration |
currentContent | ContentBySections |
Current content by sections |
html | boolean |
Returns
string
renderLocal()
renderLocal()
Render content based on local configuration.
Returns
Declaration
A Declaration is an object the holds information of a source code element.
Declaration properties
Name | Type | Description |
---|---|---|
DEFAULT_VALUE | any |
|
DISPLAY_TYPE | string |
|
FULL_TEXT | string |
|
ID | string |
|
IS_OPTIONAL | boolean |
|
LEVEL | number |
|
LINK | string |
|
NAME | string |
|
PARAMETERS | ReflectionData[] |
|
REFLECTION | Reflection |
|
RETURNS | string |
|
SECTIONS | ContentBySections |
|
SHORT_TEXT | string |
|
TEXT | string |
|
TYPE | string |
Declaration methods
Function | Returns type | Description |
---|---|---|
getChild(name) | Declaration |
|
getChildId(childName) | string |
|
getClasses(offset?) | Declaration[] |
|
getFunctionsOrMethods(offset?) | Declaration[] |
|
getInterfaces(offset?) | Declaration[] |
|
getVariablesOrProperties(offset?) | Declaration[] |
|
hasClasses() | boolean |
|
hasFunctionsOrMethods() | boolean |
|
hasInterfaces() | boolean |
|
hasVariablesOrProperties() | boolean |
|
isKind(kindString) | boolean |
|
setId(id) | this |
|
setLevel(level) | this |
getChild(name)
getChild(name)
The getChild
call signature.
Parameters
Param | Type | Description |
---|---|---|
name | string |
Returns
getChildId(childName)
getChildId(childName)
The getChildId
call signature.
Parameters
Param | Type | Description |
---|---|---|
childName | string |
Returns
string
getClasses(offset?)
getClasses(offset?)
The getClasses
call signature.
Parameters
Param | Type | Description |
---|---|---|
offset | number |
Returns
getFunctionsOrMethods(offset?)
getFunctionsOrMethods(offset?)
The getFunctionsOrMethods
call signature.
Parameters
Param | Type | Description |
---|---|---|
offset | number |
Returns
getInterfaces(offset?)
getInterfaces(offset?)
The getInterfaces
call signature.
Parameters
Param | Type | Description |
---|---|---|
offset | number |
Returns
getVariablesOrProperties(offset?)
getVariablesOrProperties(offset?)
The getVariablesOrProperties
call signature.
Parameters
Param | Type | Description |
---|---|---|
offset | number |
Returns
hasClasses()
hasClasses()
The hasClasses
call signature.
Returns
boolean
hasFunctionsOrMethods()
hasFunctionsOrMethods()
The hasFunctionsOrMethods
call signature.
Returns
boolean
hasInterfaces()
hasInterfaces()
The hasInterfaces
call signature.
Returns
boolean
hasVariablesOrProperties()
hasVariablesOrProperties()
The hasVariablesOrProperties
call signature.
Returns
boolean
isKind(kindString)
isKind(kindString)
The isKind
call signature.
Parameters
Param | Type | Description |
---|---|---|
kindString | keyof ReflectionKind |
Returns
boolean
setId(id)
setId(id)
The setId
call signature.
Parameters
Param | Type | Description |
---|---|---|
id | string |
Returns
this
setLevel(level)
setLevel(level)
The setLevel
call signature.
Parameters
Param | Type | Description |
---|---|---|
level | number |
Returns
this
The Parser
The Parser
turns source code into Declaration
ParseService methods
Function | Returns type | Description |
---|---|---|
parse(input?) | Declaration |
parse(input?)
parse(input?)
The parse
call signature.
Parameters
Param | Type | Description |
---|---|---|
input | string |
Returns
The Converter
The Converter
turns Declaration into content blocks
Converter output
A Declaration supports certain output depended on its kind:
Output | Kinds | Description |
---|---|---|
FULL | any | All content (with headings) |
SELF | any | Title, description, content WITHOUT local sections, parameters & returns (for function) |
SECTION:<SECTION_ID> | any | A local section |
VALUE | Variable , Property |
Default value |
SUMMARY_VARIABLES | Collection |
Summary table of variables |
DETAIL_VARIABLES | Collection |
Detail list of variables |
FULL_VARIABLES | Collection |
Summary table & detail list of variables |
SUMMARY_FUNCTIONS | Collection |
Summary table of functions |
DETAIL_FUNCTIONS | Collection |
Detail list of functions |
FULL_FUNCTIONS | Collection |
Summary table & detail list of functions |
SUMMARY_PROPERTIES | Interface , Class |
Summary table of properties |
DETAIL_PROPERTIES | Interface , Class |
Detail list of properties |
FULL_PROPERTIES | Interface , Class |
Summary table & detail list of properties |
SUMMARY_METHODS | Class |
Summary table of methods |
DETAIL_METHODS | Class |
Detail list of methods |
FULL_METHODS | Class |
Summary table & detail list of methods |
SUMMARY_INTERFACES | Collection |
Summary table of interfaces |
DETAIL_INTERFACES | Collection |
Detail list of interfaces |
FULL_INTERFACES | Collection |
Summary table & detail list of interfaces |
SUMMARY_CLASSES | Collection |
Summary table of classes |
DETAIL_CLASSES | Collection |
Detail list of classes |
FULL_CLASSES | Collection |
Summary table & detail list of classes |
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 }
ConvertService methods
Function | Returns type | Description |
---|---|---|
convert(declaration, output, options?) | HeadingBlock | TextBlock | ListBlock | TableBlock[] |
convert(declaration, output, options?)
convert(declaration, output, options?)
The convert
call signature.
Parameters
Param | Type | Description |
---|---|---|
declaration | Declaration |
|
output | string |
|
options | ConvertOptions |
Returns
HeadingBlock | TextBlock | ListBlock | TableBlock[]
The Renderer
The Renderer turns a rendering input into the final content
Builtin sections:
head
: Package name & descriptiontoc
: Table of contenttocx
: Table of content, with detail API reference linklicense
: License information
RenderService methods
Function | Returns type | Description |
---|---|---|
getData(rendering) | RenderingData |
|
getDataBatch(batchRendering) | BatchRenderingData |
|
render(rendering, currentContent?, html?) | string |
|
renderBatch(batchRendering, batchCurrentContent?) | BatchRenderResult |
getData(rendering)
getData(rendering)
The getData
call signature.
Parameters
Param | Type | Description |
---|---|---|
rendering | Rendering |
Returns
getDataBatch(batchRendering)
getDataBatch(batchRendering)
The getDataBatch
call signature.
Parameters
Param | Type | Description |
---|---|---|
batchRendering | BatchRendering |
Returns
render(rendering, currentContent?, html?)
render(rendering, currentContent?, html?)
The render
call signature.
Parameters
Param | Type | Description |
---|---|---|
rendering | Rendering |
|
currentContent | ContentBySections |
|
html | boolean |
Returns
string
renderBatch(batchRendering, batchCurrentContent?)
renderBatch(batchRendering, batchCurrentContent?)
The renderBatch
call signature.
Parameters
Param | Type | Description |
---|---|---|
batchRendering | BatchRendering |
|
batchCurrentContent | object |
Returns
License
@lamnhan/docsuper is released under the MIT license.
⚡️ This document is generated automatically using @lamnhan/docsuper.