feat(dgeni,docs,daffio): implement ToC for all doc kinds (#3423)

apps/daffio/src/app/docs/api/components/api-content/api-content.component.html

@@ -1,7 +1,14 @@
-<daffio-doc-article [breadcrumbs]="doc().breadcrumbs">
+<daffio-doc-article [breadcrumbs]="doc().breadcrumbs" [toc]="doc().tableOfContents">
 	@if (isApiPackage()) {
 		<daffio-api-package [doc]="doc()"></daffio-api-package>
 	} @else {
 		<div [innerHTML]="doc().contents | safe"></div>
+		@if (doc().examples.length > 0) {
+			<h2 id="examples">Examples</h2>
+		}
+		@for (example of doc().examples; track example.id) {
+			<h3 [attr.id]="example.id">{{example.caption}}</h3>
+			<div [innerHTML]="example.body | safe"></div>
+		}
 	}
 </daffio-doc-article>

apps/daffio/src/app/docs/components/default-content/default-content.component.html

@@ -1,3 +1,3 @@
-<daffio-doc-article [breadcrumbs]="doc().breadcrumbs">
+<daffio-doc-article [breadcrumbs]="doc().breadcrumbs" [toc]="doc().tableOfContents">
 	<div [innerHTML]="doc().contents | safe"></div>
 </daffio-doc-article>

apps/daffio/src/app/docs/components/table-of-contents/table-of-contents.component.spec.ts

@@ -7,15 +7,15 @@ import { By } from '@angular/platform-browser';
 import { RouterTestingModule } from '@angular/router/testing';
 
 import { DaffLinkSetModule } from '@daffodil/design/link-set';
-import { DaffGuideDoc } from '@daffodil/docs-utils';
+import { DaffDoc } from '@daffodil/docs-utils';
 
 import { DaffioDocsTableOfContentsComponent } from './table-of-contents.component';
 import { DaffioDocsFactory } from '../../testing/factories/docs.factory';
 
 describe('DaffioDocsTableOfContentsComponent', () => {
   let component: DaffioDocsTableOfContentsComponent;
   let fixture: ComponentFixture<DaffioDocsTableOfContentsComponent>;
-  let stubDaffioDoc: DaffGuideDoc;
+  let stubDaffioDoc: DaffDoc;
 
   beforeEach(waitForAsync(() => {
     TestBed.configureTestingModule({

apps/daffio/src/app/docs/guides/components/guides-content/guides-content.component.ts

@@ -5,7 +5,7 @@ import {
 } from '@angular/core';
 
 import {
-  DaffGuideDoc,
+  DaffDoc,
   DaffDocKind,
 } from '@daffodil/docs-utils';
 
@@ -23,8 +23,8 @@ import { DaffioDocsDynamicContent } from '../../../dynamic-content/dynamic-conte
     DaffioSafeHtmlPipe,
   ],
 })
-export class DaffioDocsGuidesContentComponent implements DaffioDocsDynamicContent<DaffGuideDoc> {
+export class DaffioDocsGuidesContentComponent implements DaffioDocsDynamicContent<DaffDoc> {
   static readonly kind = DaffDocKind.GUIDE;
 
-  doc = input<DaffGuideDoc>();
+  doc = input<DaffDoc>();
 }

apps/daffio/src/app/docs/testing/factories/docs.factory.ts

@@ -5,10 +5,10 @@ import { sample } from '@daffodil/core';
 import { DaffModelFactory } from '@daffodil/core/testing';
 import {
   DaffDocKind,
-  DaffGuideDoc,
+  DaffDoc,
 } from '@daffodil/docs-utils';
 
-export class MockDoc implements DaffGuideDoc {
+export class MockDoc implements DaffDoc {
   id = String(faker.datatype.number(1000));
   kind = sample(Object.values(DaffDocKind));
   title = faker.lorem.words();
@@ -27,7 +27,7 @@ export class MockDoc implements DaffGuideDoc {
 @Injectable({
   providedIn: 'root',
 })
-export class DaffioDocsFactory extends DaffModelFactory<DaffGuideDoc>{
+export class DaffioDocsFactory extends DaffModelFactory<DaffDoc>{
   constructor() {
     super(MockDoc);
   }

libs/docs-utils/src/doc/api.type.ts

@@ -1,5 +1,5 @@
-import { DaffDocExample } from './example.type';
 import { DaffDoc } from './type';
+import { DaffDocExample } from '../example/public_api';
 
 /**
  * An API doc that includes the type of the symbol.

libs/docs-utils/src/doc/package-guide.type.ts

@@ -1,17 +1,20 @@
-import { DaffApiDoc } from '@daffodil/docs-utils';
-
-import { DaffGuideDoc } from './guide.type';
+import { DaffDoc } from './type';
+import { DaffDocTableOfContents } from '../toc/public_api';
 
 /**
  * A guide doc for a package.
  */
-export interface DaffPackageGuideDoc extends DaffGuideDoc {
+export interface DaffPackageGuideDoc extends DaffDoc {
   /**
    * A list of symbol paths exported from the package.
    */
-  symbols?: Array<string>;
+  symbols: Array<string>;
+  /**
+   * A list of rendered API docs.
+   */
+  api: Array<string>;
   /**
-   * A list of API docs for symbols exported from this package.
+   * A table of contents for the API section.
    */
-  api?: Array<DaffApiDoc>;
+  apiToc: DaffDocTableOfContents;
 }

libs/docs-utils/src/doc/public_api.ts

@@ -1,6 +1,3 @@
 export * from './api.type';
-export * from './example.type';
-export * from './guide.type';
 export * from './package-guide.type';
-export * from './toc.type';
 export * from './type';

libs/docs-utils/src/doc/type.ts

@@ -1,6 +1,6 @@
-import { DaffBreadcrumb } from '@daffodil/docs-utils';
-
+import { DaffBreadcrumb } from '../breadcrumb/public_api';
 import { DaffDocKind } from '../kind/public_api';
+import { DaffDocTableOfContents } from '../toc/public_api';
 
 /**
  * A basic generated document that represents some piece of documentation.
@@ -11,4 +11,5 @@ export interface DaffDoc {
   contents: string;
   breadcrumbs: Array<DaffBreadcrumb>;
   kind: DaffDocKind;
+  tableOfContents: DaffDocTableOfContents;
 }

libs/docs-utils/src/example/public_api.ts

@@ -0,0 +1 @@
+export * from './type';

libs/docs-utils/src/doc/example.type.ts → libs/docs-utils/src/example/type.ts

@@ -2,6 +2,11 @@
  * A usage example.
  */
 export interface DaffDocExample {
+  /**
+   * The ID of the example.
+   * Since not all examples will have captions, a unique is useful for fragment anchor scrolling.
+   */
+  id: string;
   /**
    * The short caption describing the example.
    * This should be just plain text.

libs/docs-utils/src/public_api.ts

@@ -1,6 +1,9 @@
 export { crossOsFilename } from './cross-os-filename';
-export * from './kind/public_api';
+export * from './path';
+
 export * from './breadcrumb/public_api';
-export * from './nav/public_api';
 export * from './doc/public_api';
-export * from './path';
+export * from './example/public_api';
+export * from './kind/public_api';
+export * from './nav/public_api';
+export * from './toc/public_api';

libs/docs-utils/src/toc/public_api.ts

@@ -0,0 +1 @@
+export * from './type';

tools/dgeni/src/processors/add-api-symbols-to-package.ts

@@ -1,6 +1,8 @@
 import { Document } from 'dgeni';
 import type { Environment } from 'nunjucks';
 
+import { DaffApiDoc } from '@daffodil/docs-utils';
+
 import { CollectLinkableSymbolsProcessor } from './collect-linkable-symbols';
 import { API_TEMPLATES_PATH } from '../transforms/config';
 import { FilterableProcessor } from '../utils/filterable-processor.type';
@@ -30,8 +32,13 @@ export class AddApiSymbolsToPackagesProcessor implements FilterableProcessor {
 
     const ret = docs.map(doc => {
       if (this.docTypes.includes(doc.docType)) {
-        doc.symbols = CollectLinkableSymbolsProcessor.packages.get(this.lookup(doc))?.map((d) => d.path);
-        doc.api = CollectLinkableSymbolsProcessor.packages.get(this.lookup(doc))?.map((symbol) => render(this.templateFinder.getFinder()(symbol), { doc: symbol, child: true }));
+        const exportDocs = CollectLinkableSymbolsProcessor.packages.get(this.lookup(doc));
+        doc.symbols = exportDocs?.map((d) => d.path);
+        doc.api = exportDocs?.map((symbol) => render(this.templateFinder.getFinder()(symbol), { doc: symbol, child: true }));
+        doc.apiToc = exportDocs?.flatMap((symbol: DaffApiDoc) => symbol.tableOfContents.map((entry) => ({
+          ...entry,
+          lvl: entry.lvl + 1,
+        })));
       }
       return doc;
     });

tools/dgeni/src/transforms/daffodil-api-package/processors/examples.ts

@@ -1,12 +1,23 @@
 import { Document } from 'dgeni';
+import { slugify } from 'markdown-toc';
 
-import { DaffDocExample } from '@daffodil/docs-utils';
+import {
+  DaffDocExample,
+  DaffDocTableOfContents,
+} from '@daffodil/docs-utils';
 
 import { MARKDOWN_CODE_PROCESSOR_NAME } from '../../../processors/markdown';
 import { FilterableProcessor } from '../../../utils/filterable-processor.type';
 
 export const EXAMPLES_PROCESSOR_NAME = 'examples';
 
+const genExamplesToc = (examples: Array<DaffDocExample>): DaffDocTableOfContents =>
+  examples.map((example) => ({
+    content: example.caption,
+    lvl: 3,
+    slug: example.id,
+  }));
+
 /**
  * Adds subpackage entry point docs to the containing package doc.
  */
@@ -20,10 +31,20 @@ export class ExamplesProcessor implements FilterableProcessor {
   $process(docs: Array<Document>): Array<Document> {
     return docs.map((doc) => {
       if (this.docTypes.includes(doc.docType)) {
-        doc.examples = doc.tags.tagsByName.get('example')?.map((example): DaffDocExample => ({
+        doc.examples = doc.tags.tagsByName.get('example')?.map((example, i): DaffDocExample => ({
+          id: slugify(`${doc.name}-example-${i}`),
           caption: example.caption,
           body: example.body,
         })) || [];
+        doc.tableOfContents = doc.examples.length > 0 ? [
+          {
+            content: 'Examples',
+            lvl: 2,
+            // TODO: add doc-specific prefix
+            slug: 'examples',
+          },
+          ...genExamplesToc(doc.examples),
+        ] : [];
       }
       return doc;
     });