@travetto/doc 3.0.0-rc.6 → 3.0.0-rc.8

package/README.md

@@ -105,17 +105,62 @@ Options:
   -i, --input <input>      Input File (default: "DOC.ts")
   -o, --outputs <outputs>  Outputs (default: [])
   -w, --watch              Watch
-  -s, --stdout             Write to stdout (default: false)
   -h, --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.
 
 **Terminal: Sample CLI Output**
 ```bash
-$ trv doc -f html --stdout
+$ trv doc -o html
+
+<!-- This file was generated by @travetto/doc and should not be modified directly -->
+<!-- Please modify @travetto/doc/doc-exec/DOC.ts 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</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="@travetto/doc/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>
+
+Options:
+  -V, <span class="token parameter variable">--version</span>   output the version number
+  -h, <span class="token parameter variable">--help</span>      display <span class="token builtin class-name">help</span> <span class="token keyword">for</span> <span class="token builtin class-name">command</span>
+
+Commands:
+  doc <span class="token punctuation">[</span>options<span class="token punctuation">]</span>
+  <span class="token builtin class-name">help</span> <span class="token punctuation">[</span>command<span class="token punctuation">]</span>  display <span class="token builtin class-name">help</span> <span class="token keyword">for</span> <span class="token builtin class-name">command</span></code></pre>     
+      </figure>
+Wrote docs for DOC.ts
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@travetto/doc",
-  "version": "3.0.0-rc.6",
+  "version": "3.0.0-rc.8",
   "description": "Documentation support for the travetto framework",
   "keywords": [
     "docs",
@@ -24,12 +24,12 @@
     "directory": "module/doc"
   },
   "dependencies": {
-    "@travetto/base": "^3.0.0-rc.6",
+    "@travetto/base": "^3.0.0-rc.8",
     "@types/prismjs": "^1.26.0",
     "prismjs": "^1.29.0"
   },
   "peerDependencies": {
-    "@travetto/cli": "^3.0.0-rc.6"
+    "@travetto/cli": "^3.0.0-rc.9"
   },
   "peerDependenciesMeta": {
     "@travetto/cli": {

package/src/nodes.ts

@@ -19,6 +19,8 @@ const $n = <T extends string, U extends Record<string, unknown>>(t: T, values: U
   // eslint-disable-next-line @typescript-eslint/consistent-type-assertions
   ({ _type: t, ...values } as { _type: T } & U);
 
+type FormattedCommand = { formatCommand?(cmd: string, args: string[]): string };
+
 /* eslint-disable @typescript-eslint/explicit-function-return-type */
 
 /**
@@ -157,7 +159,7 @@ export const node = {
    * @param args
    * @param cfg
    */
-  Execute: (title: Content, cmd: string, args: string[] = [], cfg: RunConfig = {}) => {
+  Execute: (title: Content, cmd: string, args: string[] = [], cfg: RunConfig & FormattedCommand = {}) => {
     if (cmd !== 'trv') {
       cmd = FileUtil.resolveFile(cmd).replace(path.cwd(), '.');
     }
@@ -165,7 +167,9 @@ export const node = {
     const script = DocRunUtil.run(cmd, args, cfg);
     const prefix = !/.*\/doc\/.*[.]ts$/.test(cmd) ? '$' : '$ node ';
 
-    return node.Terminal(title, `${prefix} ${cmd} ${args.join(' ')}\n\n${script}`);
+    const commandDisplay = cfg.formatCommand?.(cmd, args) ?? `${cmd} ${args.join(' ')}`;
+
+    return node.Terminal(title, `${prefix} ${commandDisplay}\n\n${script}`);
   },
 
   /**
@@ -174,7 +178,7 @@ export const node = {
    */
   Mod(name: string, cfg?: { folder: string, displayName: string, description: string }) {
     if (!cfg) {
-      const folder = RootIndex.getModule(name)!.source;
+      const folder = RootIndex.getModule(name)!.sourcePath;
       const pkg = PackageUtil.readPackage(folder);
       cfg = {
         folder,
@@ -233,7 +237,7 @@ export const node = {
     if (!mod) {
       mod = RootIndex.mainPackage.name;
     }
-    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.source);
+    const pkg = PackageUtil.readPackage(RootIndex.getModule(mod)!.sourcePath);
     return $n('header', { title: $c(pkg.travetto?.displayName ?? pkg.name), description: $c(pkg.description), package: pkg.name, install });
   },
 

package/src/render/util.ts

@@ -46,12 +46,13 @@ export class RenderUtil {
 
     const { wrap, root } = this.#imported.get(file)!;
 
-    const manifestPkg = PackageUtil.readPackage(RootIndex.getModule('@travetto/manifest')!.source);
+    const manifestPkg = PackageUtil.readPackage(RootIndex.getModule('@travetto/manifest')!.sourcePath);
 
     const mf = RootIndex.manifest;
 
     const pkg = PackageUtil.readPackage(mf.workspacePath);
-    const repoBaseUrl = pkg.travetto?.docBaseUrl ?? mf.mainPath;
+    const mainPath = path.resolve(mf.workspacePath, mf.mainFolder);
+    const repoBaseUrl = pkg.travetto?.docBaseUrl ?? mainPath;
 
     const ctx = new RenderContext(
       file,

package/src/util/file.ts

@@ -26,8 +26,7 @@ export class FileUtil {
     let resolved = path.resolve(file);
     if (!existsSync(resolved)) {
       if (file.endsWith('.ts')) {
-        resolved = RootIndex.resolveFileImport(file);
-        resolved = RootIndex.getSourceFile(resolved);
+        resolved = RootIndex.getSourceFile(file);
       }
       if (!existsSync(resolved)) {
         throw new Error(`Unknown file to resolve: ${file}`);

package/src/util/run.ts

@@ -8,6 +8,7 @@ export type RunConfig = {
   filter?: (line: string) => boolean;
   module?: string;
   env?: Record<string, string>;
+  profiles?: string[];
   cwd?: string;
 };
 
@@ -57,7 +58,10 @@ export class DocRunUtil {
         env: {
           ...Env.export(/^(TRV_.*|NODE_.*|.*COLOR.*|PATH)$/),
           DEBUG: '0',
-          ...(config.module ? { TRV_MANIFEST: config.module } : {}),
+          TRV_MANIFEST: '',
+          TRV_BUILD: 'warn',
+          TRV_MODULE: config.module ?? '',
+          ...(config.profiles ? { TRV_PROFILES: config.profiles.join(' ') } : {}),
           ...(config.env ?? {})
         }
       }
@@ -72,7 +76,6 @@ export class DocRunUtil {
       .replace(/^(.{1,4})?Compiling[.]*/, '') // Compiling message, remove
       .replace(/[A-Za-z0-9_.\-\/\\]+\/travetto\/module\//g, '@travetto/')
       .replace(new RegExp(path.cwd(), 'g'), '.')
-      .replace(/([.]trv_cache)[_A-Za-z0-9]+/g, (_, b) => b)
       .replace(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}([.]\d{3})?Z?/g, this.#docState.getDate.bind(this.#docState))
       .replace(/\b[0-9a-f]{4}[0-9a-f\-]{8,40}\b/ig, this.#docState.getId.bind(this.#docState))
       .replace(/(\d+[.]\d+[.]\d+)-(alpha|rc)[.]\d+/g, (all, v) => v);

package/support/cli.doc.ts

@@ -1,7 +1,7 @@
 import fs from 'fs/promises';
 
-import { PackageUtil, path, RootIndex } from '@travetto/manifest';
-import { WatchUtil, ExecUtil, GlobalEnvConfig } from '@travetto/base';
+import { PackageUtil, path, RootIndex, watchFolders } from '@travetto/manifest';
+import { GlobalEnvConfig } from '@travetto/base';
 import { CliCommand, OptionConfig, ListOptionConfig } from '@travetto/cli';
 
 import { RenderUtil } from '../src/render/util';
@@ -10,7 +10,6 @@ type Options = {
   input: OptionConfig<string>;
   outputs: ListOptionConfig<string>;
   watch: OptionConfig<boolean>;
-  stdout: OptionConfig<boolean>;
 };
 
 /**
@@ -23,8 +22,7 @@ export class DocCommand extends CliCommand<Options> {
     return {
       input: this.option({ desc: 'Input File', def: 'DOC.ts' }),
       outputs: this.listOption({ desc: 'Outputs', def: [] }),
-      watch: this.boolOption({ desc: 'Watch' }),
-      stdout: this.boolOption({ desc: 'Write to stdout', def: false })
+      watch: this.boolOption({ desc: 'Watch' })
     };
   }
 
@@ -43,7 +41,7 @@ export class DocCommand extends CliCommand<Options> {
   async action(): Promise<void> {
     const docFile = path.resolve(this.cmd.input);
     if (!(await fs.stat(docFile).catch(() => false))) {
-      ExecUtil.returnResponse(`The input ${this.cmd.input} does not exist`, true);
+      console.error(`The input ${this.cmd.input} does not exist`);
       return this.exit(1);
     }
 
@@ -52,32 +50,33 @@ export class DocCommand extends CliCommand<Options> {
       this.cmd.outputs = workspacePkg.travetto?.docOutputs ?? ['README.md'];
     }
 
-    const outputs = this.cmd.outputs.map(output => [path.extname(output).substring(1), path.resolve(output)]);
+    const outputs = this.cmd.outputs.map(output => output.includes('.') ? [path.extname(output).substring(1), path.resolve(output)] : [output, null] as const);
 
     // If specifying output
     const write = async (): Promise<void> => {
       RenderUtil.purge(docFile);
       for (const [fmt, out] of outputs) {
-        const finalName = path.resolve(out);
         const result = await RenderUtil.render(docFile, fmt);
-        if (this.cmd.stdout) {
-          process.stdout.write(result);
-        } else {
+        if (out) {
+          const finalName = path.resolve(out);
           await fs.writeFile(finalName, result, 'utf8');
+        } else {
+          process.stdout.write(result);
         }
       }
     };
 
     if (this.cmd.watch) {
-      await WatchUtil.watchFile(docFile, write);
+      await watchFolders([path.dirname(docFile)], write, {
+        filter: ev => ev.action === 'update' && ev.file === docFile
+      });
     } else {
       try {
         await write();
-        ExecUtil.returnResponse(`Wrote docs for ${this.cmd.input}`);
-        return this.exit(0);
+        console.log(`Wrote docs for ${this.cmd.input}`);
       } catch (err) {
-        ExecUtil.returnResponse(`${err}`, true);
-        return this.exit(1);
+        console.error(err);
+        this.exit(1);
       }
     }
   }