@travetto/doc 8.0.0-alpha.2 → 8.0.0-alpha.20

package/README.md

@@ -13,32 +13,33 @@ npm install @travetto/doc
 yarn add @travetto/doc
 ```
 
-This module provides the ability to generate documentation in [HTML](https://en.wikipedia.org/wiki/HTML) and/or [Markdown](https://en.wikipedia.org/wiki/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.
+This module provides the ability to generate documentation in [HTML](https://en.wikipedia.org/wiki/HTML) and/or [Markdown](https://en.wikipedia.org/wiki/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**
 ```typescript
 /** @jsxImportSource @travetto/doc/support */
 import { c } from '@travetto/doc';
 
-export const text = <>
-  <c.StdHeader />
-
-  Sample documentation for fictional module.  This module fictitiously relies upon <c.Module 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>
-</>;
+export const text = (
+  <>
+    <c.StdHeader />
+    Sample documentation for fictional module. This module fictitiously relies upon <c.Module 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**
@@ -51,12 +52,15 @@ export interface DocumentShape {
 
 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.
+**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
+   *  `CliHelpDescription` - Standardized CLI command help description
+   *  `CliHelpExecution` - Standardized CLI command help execution
+   *  `CliHelpSection` - Standardized CLI command help section
    *  `Code` - Code sample
    *  `CodeLink` - Code link with regexp for detecting line
    *  `Command` - Command invocation
@@ -81,25 +85,31 @@ As you can see, you need to export a field named `text` as the body of the help
    *  `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.
+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](https://travetto.dev) based modules as needed.  The `d.module` 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.
+You can also link to other [Travetto](https://travetto.dev) based modules as needed. The `d.module` 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.
+Generate documentation outputs from a module `DOC.tsx` entry file.
 
-**Terminal: CLI Doc Help**
+**Terminal: Help for doc**
 ```bash
 $ trv doc --help
 
 Usage: doc [options]
 
+Description:
+  Generate documentation outputs from a module `DOC.tsx` entry file.
+
+  Supports multiple output formats/targets and optional watch mode for
+  iterative documentation authoring.
+
 Options:
   -i, --input <string>    Input File (default: "DOC.tsx")
-  -o, --outputs <string>  Outputs (default: ["README.md"])
+  -o, --outputs <string>  Outputs (default: ["README.md","DOC.html"])
   -w, --watch             Watch? (default: false)
-  -h, --help              display help for command
+  --help                  display help for command
 ```
 
 By default, running the command will output the [Markdown](https://en.wikipedia.org/wiki/Markdown) content directly to the terminal.
@@ -123,7 +133,7 @@ $ trv doc -o html
 <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.
+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>
@@ -137,7 +147,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
 
 </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 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>
 
@@ -152,7 +162,7 @@ Sample documentation for fictional module.  This module fictitiously relies upon
 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.
-  <span class="token function">service</span>    Allows <span class="token keyword">for</span> running services</code></pre>
+  doc        Generate documentation outputs from a module <span class="token variable"><span class="token variable">`</span>DOC.tsx<span class="token variable">`</span></span> entry file.
+  <span class="token function">service</span>    Manage development services <span class="token punctuation">(</span>start/stop/restart/status<span class="token punctuation">)</span> across the workspace.</code></pre>
   </figure>
 ```

package/__index__.ts

@@ -1,6 +1,6 @@
-export { type JSXElement as DocJSXElement, isJSXElement as isDocJSXElement } from './support/jsx-runtime.ts';
 export { c, d, JSXElementByFn as DocJSXElementByFn } from './src/jsx.ts';
 export { MODULES as module } from './src/mapping/module.ts';
 export { DocFileUtil } from './src/util/file.ts';
-export { DocRunUtil, COMMON_DATE } from './src/util/run.ts';
-export { PackageDocUtil } from './src/util/package.ts';
+export { PackageDocUtil } from './src/util/package.ts';
+export { COMMON_DATE, DocRunUtil } from './src/util/run.ts';
+export { isJSXElement as isDocJSXElement, type JSXElement as DocJSXElement } from './support/jsx-runtime.ts';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "8.0.0-alpha.2",
+  "version": "8.0.0-alpha.20",
   "description": "Documentation support for the Travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,14 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/runtime": "^8.0.0-alpha.2",
+    "@travetto/runtime": "^8.0.0-alpha.20",
+    "@types/markdown-it": "^14.1.2",
     "@types/prismjs": "^1.26.6",
+    "markdown-it": "^14.3.0",
     "prismjs": "^1.30.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^8.0.0-alpha.3"
+    "@travetto/cli": "^8.0.0-alpha.28"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/jsx.ts

@@ -1,20 +1,26 @@
-import { castTo, TypedObject } from '@travetto/runtime';
+import { type Class as ClassType, castTo, TypedObject } from '@travetto/runtime';
 
+import { type JSXComponentFunction as CompFn, createElement, type JSXElement } from '../support/jsx-runtime.ts';
 import type { LIBRARIES } from './mapping/library.ts';
 import type { MODULES } from './mapping/module.ts';
-import type { CodeProps, CodeSourceInput, RunConfig } from './util/types.ts';
-
-import { createElement, type JSXElement, type JSXComponentFunction as CompFn } from '../support/jsx-runtime.ts';
 import { PackageDocUtil } from './util/package.ts';
+import type { CodeProps, CodeSourceInput, RunConfig } from './util/types.ts';
 
-type InstallProps = { title: string, pkg: string };
-type ExecProps = { title: string, cmd: string, args?: string[], config?: RunConfig & { formatCommand?(cmd: string, args: string[]): string } };
-type StdHeaderProps = { module?: string, install?: boolean };
-type HeaderProps = { title: string, description?: string };
+type InstallProps = { title: string; pkg: string };
+type ExecProps = {
+  title: string;
+  cmd: string;
+  args?: string[];
+  config?: RunConfig & { formatCommand?(cmd: string, args: string[]): string };
+};
+type CliHelpProps = { commandClass: ClassType };
+type CliHelpExecutionProps = CliHelpProps & { config?: RunConfig };
+type StdHeaderProps = { module?: string; install?: boolean };
+type HeaderProps = { title: string; description?: string };
 type ModuleProps = { name: keyof typeof MODULES };
 type LibraryProps = { name: keyof typeof LIBRARIES };
-type LinkProps = { title: string, href: string, line?: number };
-type CodeLinkProps = { title: string, src: CodeSourceInput, startRe: RegExp };
+type LinkProps = { title: string; href: string; line?: number };
+type CodeLinkProps = { title: string; src: CodeSourceInput; startRe: RegExp };
 type Named = { name: string };
 type Titled = { title: string };
 
@@ -46,23 +52,48 @@ const Config: CompFn<CodeProps> = () => EMPTY; // Configuration block
 const StdHeader: CompFn<StdHeaderProps> = () => EMPTY; // Standard module header
 const Header: CompFn<HeaderProps> = () => EMPTY; // Basic module header
 const Execution: CompFn<ExecProps> = () => EMPTY; // Run a command, and include the output as part of the document
+const CliHelpSection: CompFn<CliHelpProps> = () => EMPTY; // Standardized CLI command help section
+const CliHelpDescription: CompFn<CliHelpProps & { short?: boolean }> = () => EMPTY; // Standardized CLI command help description
+const CliHelpExecution: CompFn<CliHelpExecutionProps> = () => EMPTY; // Standardized CLI command help execution
 
 const Module: CompFn<ModuleProps> = () => EMPTY; // Node Module Reference
 const Library: CompFn<LibraryProps> = () => EMPTY; // Library reference
 
 export const c = {
-  Input, Field, Method, Command, Path, Class,
-  Anchor, Library, Ref, File, Image, CodeLink,
-  Module, Note, Header, StdHeader,
-  Section, SubSection, SubSubSection,
-  Code, Execution, Terminal, Install, Config
+  Input,
+  Field,
+  Method,
+  Command,
+  Path,
+  Class,
+  Anchor,
+  Library,
+  Ref,
+  File,
+  Image,
+  CodeLink,
+  Module,
+  Note,
+  Header,
+  StdHeader,
+  Section,
+  SubSection,
+  SubSubSection,
+  Code,
+  Execution,
+  Terminal,
+  Install,
+  Config,
+  CliHelpSection,
+  CliHelpDescription,
+  CliHelpExecution
 } as const;
 
 type C = typeof c;
 
 // @ts-expect-error
 export type JSXElementByFn<K extends keyof C> = JSXElement<C[K], Parameters<C[K]>[0]>;
-export type JSXElements = { [K in keyof C]: JSXElementByFn<K>; };
+export type JSXElements = { [K in keyof C]: JSXElementByFn<K> };
 
 export const EMPTY_ELEMENT = EMPTY;
 
@@ -83,7 +114,8 @@ function CodeLinker(titleOrNode: string | JSXElement, src?: string, startRe?: Re
     props = { title: titleOrNode, src: src!, startRe: startRe! };
   } else if (titleOrNode.type === Code) {
     const node: JSXElementByFn<'Code'> = castTo(titleOrNode);
-    const srcName = typeof node.props.src === 'string' ? node.props.src : (typeof node.props.src === 'function' ? node.props.src.name : '<UNNAMED>');
+    const srcName =
+      typeof node.props.src === 'string' ? node.props.src : typeof node.props.src === 'function' ? node.props.src.name : '<UNNAMED>';
     props = {
       title: node.props.title ?? srcName,
       src: node.props.src,
@@ -106,5 +138,7 @@ export const d = {
   field: (name: string) => createElement(c.Field, { name }),
   library: (name: keyof typeof LIBRARIES) => createElement(c.Library, { name }),
   module: (name: keyof typeof MODULES) => createElement(c.Module, { name }),
-  get trv() { return PackageDocUtil.getPackageCommand('trv'); },
-};
+  get trv() {
+    return PackageDocUtil.getPackageCommand('trv');
+  }
+};

package/src/mapping/library.ts

@@ -7,7 +7,7 @@ export const LIBRARIES = {
   Npm: { title: 'Npm', href: 'https://docs.npmjs.com/downloading-and-installing-node-js-and-npm' },
   Yarn: { title: 'Yarn', href: 'https://yarnpkg.com' },
   Pnpm: { title: 'Pnpm', href: 'https://pnpm.io/' },
-  Eslint: { title: 'ESLint', href: 'https://eslint.org/' },
+  Biome: { title: 'Biome', href: 'https://biomejs.dev/' },
   Rollup: { title: 'Rollup', href: 'https://rollupjs.org/' },
   TSConfig: { title: 'TS Config', href: 'https://www.typescriptlang.org/docs/handbook/tsconfig-json.html' },
 
@@ -35,7 +35,10 @@ export const LIBRARIES = {
   DependencyInjection: { title: 'Dependency injection', href: 'https://en.wikipedia.org/wiki/Dependency_injection' },
   OpenAPI: { title: 'OpenAPI', href: 'https://github.com/OAI/OpenAPI-Specification' },
   JSDoc: { title: 'JSDoc', href: 'http://usejsdoc.org/about-getting-started.html' },
-  CodeLens: { title: 'CodeLens', href: 'https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code' },
+  CodeLens: {
+    title: 'CodeLens',
+    href: 'https://code.visualstudio.com/api/language-extensions/programmatic-language-features#codelens-show-actionable-context-information-within-source-code'
+  },
   ORM: { title: 'Object Relationship Mapping', href: 'https://en.wikipedia.org/wiki/Object%E2%80%93relational_mapping' },
   UUID: { title: 'UUID', href: 'https://en.wikipedia.org/wiki/Universally_unique_identifier' },
 
@@ -113,5 +116,5 @@ export const LIBRARIES = {
   ServerlessExpress: { title: 'aws-serverless-express', href: 'https://github.com/awslabs/aws-serverless-express/blob/master/README.md' },
   AwsLambdaFastify: { title: '@fastify/aws-lambda', href: 'https://github.com/fastify/aws-lambda-fastify/blob/master/README.md' },
   Fastify: { title: 'fastify', href: 'https://www.fastify.io/' },
-  Koa: { title: 'koa', href: 'https://koajs.com/' },
-} as const;
+  Koa: { title: 'koa', href: 'https://koajs.com/' }
+} as const;