Documentation

Documentation support for the Travetto framework

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.

Node Types

• 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

Libraries

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.

Modules

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.

CLI - doc

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>