Install: @travetto/doc
npm install @travetto/doc
# or
yarn add @travetto/doc
This module provides the ability to generate documentation in HTML and/or Markdown. The module relies on integrating with the source of the project, and providing a fully referenced code-base. This allows for automatic updates when code is changed and/or refactored.
Code: Document Sample
/** @jsxImportSource @travetto/doc */
import { c } from '@travetto/doc';
export const text = <>
<c.StdHeader />
Sample documentation for fictional module. This module fictitiously relies upon <c.Mod name='Cache' /> functionality.
<ol>
<li>First</li>
<li>Second</li>
<li><c.Path name='Special' /></li>
</ol>
<c.Section title='Content'>
<c.Code title='Document Sample' src='./src/test.ts' />
<c.SubSection title='Output'>
<c.Execution title='Run program' cmd='trv' />
</c.SubSection>
</c.Section>
</>;
Code: Document Context
export interface DocumentShape {
text: JSXElement | JSXElement[] | (() => Promise<JSXElement | JSXElement[]>);
wrap?: Wrapper;
}
As you can see, you need to export a field named text
as the body of the help text. The text
field can be either a direct invocation or an async function that returns the expected document output.
Note: By design all the node types provided are synchronous in nature. This is intentionally, specifically with respect to invoking commands and ensuring singular operation.
-
Anchor
- In page anchor reference -
Class
- Class reference -
Code
- Code sample -
CodeLink
- Code link with regexp for detecting line -
Command
- Command invocation -
Config
- Configuration block -
Execution
- Run a command, and include the output as part of the document -
Field
- Field reference -
File
- File reference -
Header
- Basic module header -
Image
- Image reference -
Input
- Input text -
Install
- Installing a package or a program -
Library
- Library reference -
Method
- Method declaration -
Mod
- Node Module Reference -
Note
- A note -
Path
- Path reference -
Ref
- File reference -
Section
- Primary section -
StdHeader
- Standard module header -
SubSection
- Sub-section -
SubSubSection
- Sub-sub-section -
Terminal
- Terminal output
Some of the more common libraries are provided as the d.library
method. The purpose of this is to have consistent references to common utilities to help keep external linking simple.
You can also link to other Travetto based modules as needed. The d.mod
object relies on what is already imported into your project, and reference the package.json of the related module. If the module is not installed, doc generation will fail.
The run command allows for generating documentation output.
Terminal: CLI Doc Help
$ trv doc --help
Usage: doc [options]
Options:
-i, --input <string> Input File (default: "DOC.tsx")
-o, --outputs <string> Outputs (default: ["README.md"])
-w, --watch Watch? (default: false)
-h, --help display help for command
By default, running the command will output the Markdown content directly to the terminal.
Terminal: Sample CLI Output
$ trv doc -o html
<!-- This file was generated by @travetto/doc and should not be modified directly -->
<!-- Please modify ./doc-exec/DOC.tsx and execute "npx trv doc" to rebuild -->
<h1>@travetto-doc/doc</h1>
<figure class="install">
<figcaption class="install">Install @travetto-doc/doc
</figcaption>
<pre><code class="language-bash"><span class="token function">npm</span> <span class="token function">install</span> @travetto-doc/doc
<span class="token comment"># or</span>
<span class="token function">yarn</span> <span class="token function">add</span> @travetto-doc/doc</code></pre>
</figure>
Sample documentation for fictional module. This module fictitiously relies upon <a class="module-link" href="https://github.com/travetto/travetto/tree/main/module/cache" title="Caching functionality with decorators for declarative use.">Caching</a> functionality.
<ol> <li>First</li>
<li>Second</li>
<li><code class="item path">Special</code></li>
</ol>
<h2 id="content">Content</h2>
<figure class="code">
<figcaption class="code">Document Sample
<cite><a target="_blank" href="./doc-exec/src/test.ts">Source</a></cite>
</figcaption>
<pre><code class="language-typescript"><span class="token keyword">class</span> <span class="token class-name">TestFile</span> <span class="token punctuation">{{'{'}}</span>
<span class="token keyword">static</span> <span class="token function">method</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">:</span> <span class="token keyword">void</span> <span class="token punctuation">{{'{'}}</span> <span class="token punctuation">{{'}'}}</span>
<span class="token punctuation">{{'}'}}</span></code></pre>
</figure>
<h3 id="output">Output</h3>
<figure class="terminal">
<figcaption class="terminal">Run program
</figcaption>
<pre><code class="language-bash">$ trv
Usage: <span class="token punctuation">[</span>options<span class="token punctuation">]</span> <span class="token punctuation">[</span>command<span class="token punctuation">]</span>
Commands:
doc Command line support <span class="token keyword">for</span> generating module docs.</code></pre>
</figure>