`fliegdoc`

Install using

npm install fliegdoc

Exported Members

You can access these members by importing the module:

import { member } from 'fliegdoc';

function buildTreeForConfig (...)
function getConfig (...)
function setConfig (...)
function buildModuleTree (...)
interface Module
interface FliegdocConfig
variable DEFAULT_CONFIG
type ModuleTree
type ModuleTreeNode
type Tree
interface Theme
- isBrowserViewable
- onBuild (...)
type CreateFileFunction
function serveStatic (...)
function serveDynamic (...)
function buildStatic (...)
variable HTMLTheme

`buildTreeForConfig (...)`

function buildTreeForConfig ( ) : Tree

Builds a Tree for getConfig.

You can set the config beforehand using setConfig.

@returns:

the generated documentation-ready Tree

@example:

import { buildTreeForConfig, setConfig } from 'fliegdoc';

setConfig(config);
const tree = buildTreeForConfig();

`getConfig (...)`

function getConfig ( ) : FliegdocConfig

Returns the current config

@returns:

current config

@see:

setConfig

@example:

import { getConfig } from 'fliegdoc';

console.log('current config:', getConfig());

`setConfig (...)`

function setConfig ( config : Partial<FliegdocConfig> , basePath : string = process.cwd() ) : void

Overrides the current config using the config on top of the DEFAULT_CONFIG

@param:

config - overrides of the DEFAULT_CONFIG

@param:

basePath - the base path of the config file, from which relative paths get resolved

@example:

import { setConfig } from 'fliegdoc';

const config = JSON.parse(
	fs.readFileSync(filepath).toString()
)

setConfig(config, path.dirname(filepath));

`buildModuleTree (...)`

function buildModuleTree ( module : Module ) : [moduleName: string, moduleTree: ModuleTree]

Generates a ModuleTree for the passed

@param:

module - the module configuration for which the tree should get generated

@returns:

module name and ModuleTree

@example:

import { buildModuleTree } from 'fliegdoc';

buildModuleTree({
	tsconfig,
	package,
	mainFile
});

`Module`

interface Module

A module/npm package

Must include a package.json file with a unique name

Properties

`package`

Type: string

Absolute path to the module's package.json

`tsconfig`

Type: string

Absolute path to the tsconfig.json

`mainFile`

Type: string

Relative path from the tsconfig includes to the module's main file, exporting all members

@example:

main.ts

`FliegdocConfig`

interface FliegdocConfig

The configuration for running fliegdoc

Properties

`readme`

Type: string

Path to the root project's README.md

`outDir`

Type: string

Path to the folder in which the documentation gets generated

`baseUrl`

Type: string

Base url of the domain to which the docs get deployed, including a trailing /

Default value: '/'

`title`

Type: string

Title of the project, that gets printed in the header

`externalLinks`

Type: Record<string, string>

External navigation links for the header in a key-value-manner, where the key is the label and the value the link.

`hidePrivateMembers`

Type: boolean

Hide private class members in the documentation

Default value: true

`theme`

Type: Theme

The theme that gets used.

Default value: HTMLTheme

`DEFAULT_CONFIG`

const : FliegdocConfig

The default config parameters.

Uses a README.md, package.json, and tsconfig.json file in the cwd and main.ts in the sources configured in the tsconfig.json

`ModuleTree`

type ModuleTree

Alias for: (Record<string, unknown> & { name: string; declarations: ModuleTreeNode[]; })[]

A documentation-ready tree for a single module

`ModuleTreeNode`

type ModuleTreeNode < T = unknown >

Alias for: { type: string; name: string; declarations: Array<T>; [key: string]: unknown; }

A node in a ModuleTree

`Tree`

type Tree

Alias for: { [moduleName: string]: ModuleTree; }

A documentation-ready tree for multiple modules

`Theme`

interface Theme

A theme configuration usable with fliegdoc.

An object implementing this interface gets passed to setConfig in the theme of the FliegdocConfig.

Properties

`isBrowserViewable`

Type: boolean

Whether this theme is viewable in the browser.

E.g., an HTML-theme would be browser-viewable, while a LaTeX theme wouldn't.

Methods

`onBuild (...)`

function onBuild ( tree : Tree , config : FliegdocConfig , createFile : CreateFileFunction ) : Promise<void>

Builds the theme, by generating its output files.

This must only use the createFile function to interact with the file system for serveDynamic to work.

@param:

tree - the documentation-ready AST

@param:

config - the config used for the build

@param:

createFile - a function to create a file in the output folder

`CreateFileFunction`

type CreateFileFunction

Alias for: ( path: string, content: Buffer, mimetype: string ) => Promise<void>

Write to a file inside the config.outDir, creating any parent directories, if necessary.

@param:

path - the absolute path to the output file, must be inside the config.outDir.

@param:

content - the file's content

@param:

mimetype - the file's mime type

@example:

createFile('index.html', 'content', 'text/html')

`serveStatic (...)`

function serveStatic ( port : number = 3000 ) : void

Starts an HTTP server on port and statically serves the documentation in the config's outDir.

@param:

port - the port on which the documentation gets served

@throws:

Error - if the theme isn't browser-viewable, i.e., if Theme.isBrowserViewable is false

@example:

import { buildTreeForConfig, serveDynamic, buildStatic } from 'fliegdoc';

const tree = buildTreeForConfig();
await buildStatic(tree);
serveStatic(port);

`serveDynamic (...)`

async function serveDynamic ( tree : Tree , port : number = 3000 ) : Promise<void>

Starts an http server on port and serves the documentation.

Instead of writing the docs to the actual file system, this just generates them into a "virtual" file system.

NOTE: This is great for quickly reviewing the docs, but please keep in mind that all files get saved in-memory. If a theme outputs a lot of images or other bigger files, this might pose a problem.

@param:

tree - the documentation tree

@param:

port - the port on which the documentation gets served

@throws:

Error - if the theme isn't browser-viewable, i.e., if Theme.isBrowserViewable is false

@example:

import { buildTreeForConfig, serveDynamic } from 'fliegdoc';

const tree = buildTreeForConfig();
serveDynamic(tree, port);

`buildStatic (...)`

async function buildStatic ( tree : Tree ) : Promise<void>

Builds the static documentation from tree to the config's outDir.

@param:

tree - the documentation tree

@example:

import { buildTreeForConfig, buildStatic } from 'fliegdoc';

const tree = buildTreeForConfig();
await buildStatic(tree);

`HTMLTheme`

const : Theme

The default HTML theme.

Generates individual pages, per module, and uses all configuration parameters like config.title.

Rendering gets done using templates written in ETA.