feat(dgeni,daffio): implement ToC for package guide API symbols (#3440)

Author: griest024

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

@@ -3,6 +3,6 @@
 		On this page
 	</div>
 	<div class="daffio-docs-table-of-contents__links">
-		<a *ngFor="let entry of tableOfContents"class="daffio-docs-table-of-contents__item daffio-docs-table-of-contents__item--level-{{entry.lvl}}" routerLink="./" [fragment]="entry.slug">{{ entry.content }}</a>
+		<a *ngFor="let entry of tableOfContents"class="daffio-docs-table-of-contents__item daffio-docs-table-of-contents__item--level-{{entry.lvl}}" routerLink="./" queryParamsHandling="merge" [fragment]="entry.slug">{{ entry.content }}</a>
 	</div>
 </aside>

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

@@ -1,7 +1,11 @@
 import { Document } from 'dgeni';
+import { slugify } from 'markdown-toc';
 import type { Environment } from 'nunjucks';
 
-import { DaffApiDoc } from '@daffodil/docs-utils';
+import {
+  DaffApiDoc,
+  DaffDocTableOfContents,
+} from '@daffodil/docs-utils';
 
 import { CollectLinkableSymbolsProcessor } from './collect-linkable-symbols';
 import { API_TEMPLATES_PATH } from '../transforms/config';
@@ -33,12 +37,20 @@ export class AddApiSymbolsToPackagesProcessor implements FilterableProcessor {
     const ret = docs.map(doc => {
       if (this.docTypes.includes(doc.docType)) {
         const exportDocs = CollectLinkableSymbolsProcessor.packages.get(this.lookup(doc));
-        doc.symbols = exportDocs?.map((d) => d.path);
+        doc.symbols = exportDocs?.map((d) => d.slug);
         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,
-        })));
+        doc.apiToc = exportDocs?.flatMap((symbol: Document & DaffApiDoc): DaffDocTableOfContents => [
+          {
+            content: symbol.name,
+            lvl: 2,
+            slug: slugify(symbol.name),
+          },
+          ...symbol.tableOfContents.map((entry) => ({
+            ...entry,
+            lvl: entry.lvl + 1,
+            slug: entry.slug === 'examples' ? `${symbol.slug}-examples` : entry.slug,
+          })),
+        ]);
       }
       return doc;
     });

tools/dgeni/src/processors/markdown.ts

@@ -92,6 +92,7 @@ export class MarkdownCodeProcessor implements FilterableProcessor {
           }));
         }
         this.docDescription = null;
+        doc.slug = slugify(doc.name || doc.title);
       };
       return doc;
     });

tools/dgeni/src/templates/api/base.template.html

@@ -1,5 +1,5 @@
 {% block header %}
-{$'<h3>' if child else '<h1>'$}{$ doc.name $}{$'</h3>' if child else '</h1>'$}
+{$'<h3 id="' + doc.slug + '"><a href="' + doc.path + '">' if child else '<h1>'$}{$ doc.name $}{$'</a></h3>' if child else '</h1>'$}
 {% endblock %}
 <p>{$ doc.description $}</p>
 

tools/dgeni/src/templates/api/class.template.html

@@ -10,17 +10,19 @@
 <span class="selectors__name"><code>{$ doc.decorators[0].argumentInfo[0].selector $}</code></span>
 {% endif %}
 
-{$'<h4>' if child else '<h2>'$}Properties{$'<h4>' if child else '<h2>'$}
-<table>
-  <thead>
-    <tr>
-      <th>Name</th>
-      <th>Type</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  {%- for i in range(0, doc.members.length) %}
-    {$ member(doc.members[i]) $}
-  {% endfor -%}
-</table>
+{% if doc.members.length > 0 %}
+	{$'<h4>' if child else '<h2>'$}Properties{$'</h4>' if child else '</h2>'$}
+	<table>
+		<thead>
+			<tr>
+				<th>Name</th>
+				<th>Type</th>
+				<th>Description</th>
+			</tr>
+		</thead>
+		{%- for i in range(0, doc.members.length) %}
+			{$ member(doc.members[i]) $}
+		{% endfor -%}
+	</table>
+{% endif %}
 {% endblock %}

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

@@ -40,7 +40,6 @@ export class ExamplesProcessor implements FilterableProcessor {
           {
             content: 'Examples',
             lvl: 2,
-            // TODO: add doc-specific prefix
             slug: 'examples',
           },
           ...genExamplesToc(doc.examples),

tools/dgeni/src/transforms/daffodil-guides-package/index.ts

@@ -86,7 +86,7 @@ const base = new Package('daffodil-guides-base', [daffodilBasePackage])
     generateNavList.transform = (docs) => generateNavigationTrieFromDocuments(docs.map(transformGuideDoc), { id: '', title: '', path: '' });
   })
   .config((convertToJson: ConvertToJsonProcessor) => {
-    convertToJson.extraFields.push('api');
+    convertToJson.extraFields.push('api', 'apiToc');
   });
 
 // global