docs(nxdev): consolidate documentats consumption (#10546)

docs/map.json

@@ -1,7 +1,7 @@
 [
   {
-    "name": "Nx",
-    "id": "default",
+    "name": "Nx docs",
+    "id": "nx-documentation",
     "itemList": [
       {
         "name": "Getting Started",
@@ -692,8 +692,8 @@
     ]
   },
   {
-    "name": "Nx Cloud",
-    "id": "nx-cloud",
+    "name": "Nx Cloud docs",
+    "id": "nx-cloud-documentation",
     "itemList": [
       {
         "name": "Intro",

nx-dev/data-access-documents/src/lib/documents.api.ts

@@ -14,6 +14,7 @@ export class DocumentsApi {
     private readonly options: {
       publicDocsRoot: string;
       documentSources: DocumentMetadata[];
+      addAncestor: { id: string; name: string } | null;
     }
   ) {
     if (!options.publicDocsRoot) {
@@ -22,12 +23,23 @@ export class DocumentsApi {
     if (!options.documentSources) {
       throw new Error('public document sources cannot be undefined');
     }
+
+    const itemList: DocumentMetadata[] = options.documentSources.flatMap(
+      (x) => x.itemList
+    ) as DocumentMetadata[];
+
     this.documents = {
       id: 'documents',
       name: 'documents',
-      itemList: options.documentSources.flatMap(
-        (x) => x.itemList
-      ) as DocumentMetadata[],
+      itemList: !!this.options.addAncestor
+        ? [
+            {
+              id: this.options.addAncestor.id,
+              name: this.options.addAncestor.name,
+              itemList,
+            },
+          ]
+        : itemList,
     };
   }
 

nx-dev/data-access-menu/src/lib/menu.api.ts

@@ -12,7 +12,7 @@ export class MenuApi {
 
   constructor(
     private readonly documents: DocumentMetadata,
-    private readonly packageDocuments: DocumentMetadata[]
+    private readonly packageDocuments: DocumentMetadata[] = []
   ) {}
 
   getMenu(): Menu {
@@ -23,13 +23,12 @@ export class MenuApi {
     const items = createMenuItems(this.documents);
     if (items) {
       menu = {
-        sections: [
-          getBasicSection(items),
-          getDeepDiveSection(items),
-          // getApiSection(items),
-          this.getReferenceApiMenuSection(),
-        ],
+        sections: [getBasicSection(items), getDeepDiveSection(items)],
       };
+      if (!!this.packageDocuments.length)
+        menu.sections.push(
+          this.getReferenceApiMenuSection(this.packageDocuments)
+        );
     } else {
       throw new Error(`Cannot find any documents`);
     }
@@ -38,11 +37,13 @@ export class MenuApi {
     return menu;
   }
 
-  getReferenceApiMenuSection(): MenuSection {
+  getReferenceApiMenuSection(
+    packageDocuments: DocumentMetadata[]
+  ): MenuSection {
     const documents: DocumentMetadata = {
       id: 'packages',
       name: 'Packages',
-      itemList: this.packageDocuments,
+      itemList: packageDocuments,
     };
 
     const items = createMenuItems(documents);

nx-dev/nx-dev/lib/api.ts

@@ -3,7 +3,7 @@ import { MenuApi } from '@nrwl/nx-dev/data-access-menu';
 import { PackagesApi } from '@nrwl/nx-dev/data-access-packages/node-only';
 import { DocumentMetadata } from '@nrwl/nx-dev/models-document';
 
-// Imports JSON directly so they can be bundled into the app and functions.
+// Imports JSON directly, so they can be bundled into the app and functions.
 // Also provides some test safety.
 import documents from '../public/documentation/map.json';
 import packages from '../public/documentation/packages.json';
@@ -13,15 +13,16 @@ export const packagesApi = new PackagesApi({
   packagesIndex: packages,
 });
 
-export const documentsApi = new DocumentsApi({
+export const nxDocumentsApi = new DocumentsApi({
   publicDocsRoot: 'nx-dev/nx-dev/public/documentation',
   documentSources: [
-    documents.find((x) => x.id === 'default'),
+    documents.find((x) => x.id === 'nx-documentation'),
     documents.find((x) => x.id === 'additional-api-references'),
   ].filter((x) => !!x) as DocumentMetadata[],
+  addAncestor: null,
 });
 
-export const menuApi = new MenuApi(
-  documentsApi.getDocuments(),
+export const nxMenuApi = new MenuApi(
+  nxDocumentsApi.getDocuments(),
   packagesApi.getPackageDocuments().itemList as DocumentMetadata[]
 );

nx-dev/nx-dev/pages/[...segments].tsx

@@ -10,7 +10,7 @@ import { Footer, Header } from '@nrwl/nx-dev/ui-common';
 import cx from 'classnames';
 import Router from 'next/router';
 import { useCallback, useEffect, useState } from 'react';
-import { documentsApi, menuApi, packagesApi } from '../lib/api';
+import { nxDocumentsApi, nxMenuApi, packagesApi } from '../lib/api';
 
 interface DocumentationPageProps {
   menu: Menu;
@@ -143,7 +143,7 @@ export async function getStaticProps({
 }: {
   params: { segments: string[] };
 }) {
-  const menu = menuApi.getMenu();
+  const menu = nxMenuApi.getMenu();
 
   if (params.segments[0] === 'packages') {
     let pkg: PackageMetadata | null = null;
@@ -170,7 +170,7 @@ export async function getStaticProps({
       return {
         props: {
           document: null,
-          menu: menuApi.getMenu(),
+          menu: nxMenuApi.getMenu(),
           pkg,
           schemaRequest: null,
         },
@@ -180,7 +180,7 @@ export async function getStaticProps({
     return {
       props: {
         document: null,
-        menu: menuApi.getMenu(),
+        menu: nxMenuApi.getMenu(),
         pkg,
         schemaRequest: {
           type: params.segments[2],
@@ -192,7 +192,7 @@ export async function getStaticProps({
 
   let document: DocumentData | undefined;
   try {
-    document = documentsApi.getDocument(params.segments);
+    document = nxDocumentsApi.getDocument(params.segments);
   } catch (e) {
     // Do nothing
   }
@@ -220,7 +220,7 @@ export async function getStaticPaths() {
   return {
     paths: [
       ...packagesApi.getStaticPackagePaths(),
-      ...documentsApi.getStaticDocumentPaths(),
+      ...nxDocumentsApi.getStaticDocumentPaths(),
     ],
     fallback: 'blocking',
   };

scripts/documentation/open-graph/generate-images.ts

@@ -5,7 +5,7 @@ import { resolve } from 'path';
 const mapJson = readJSONSync('./docs/map.json', 'utf8');
 
 const documents: any[] = [
-  ...mapJson.find((x) => x.id === 'default')?.['itemList'],
+  ...mapJson.find((x) => x.id === 'nx-documentation')?.['itemList'],
   ...mapJson.find((x) => x.id === 'additional-api-references')?.['itemList'],
 ].filter(Boolean);