feat(docs-utils,dgeni): extract docsgen pathing helpers (#3039)

libs/docs-utils/src/kind/helpers.spec.ts

@@ -0,0 +1,73 @@
+import { DaffDocKind } from './enum';
+import {
+  daffDocsGetKind,
+  daffDocsGetLinkUrl,
+} from './helpers';
+
+describe('@daffodil/docs-utils | daffDocsGetKind', () => {
+  describe('for a API path', () => {
+    it('should return API kind', () => {
+      const path = '/libs/core/sub/src/symbol.ts';
+      const result = daffDocsGetKind(path);
+      expect(result).toEqual(DaffDocKind.API);
+    });
+  });
+
+  describe('for a package guide path', () => {
+    it('should return package kind', () => {
+      const path = '/libs/core/guides/test/guide.md';
+      const result = daffDocsGetKind(path);
+      expect(result).toEqual(DaffDocKind.PACKAGE);
+    });
+  });
+
+  describe('for a global guide path', () => {
+    it('should return guide kind', () => {
+      const path = '/docs/guides/test/guide.md';
+      const result = daffDocsGetKind(path);
+      expect(result).toEqual(DaffDocKind.GUIDE);
+    });
+  });
+
+  describe('for a global explanation path', () => {
+    it('should return explanation kind', () => {
+      const path = '/docs/explanations/test/guide.md';
+      const result = daffDocsGetKind(path);
+      expect(result).toEqual(DaffDocKind.EXPLANATION);
+    });
+  });
+});
+
+describe('@daffodil/docs-utils | daffDocsGetLinkUrl', () => {
+  describe('for a API path', () => {
+    it('should return an API link', () => {
+      const path = '/libs/core/sub/src/symbol.ts';
+      const result = daffDocsGetLinkUrl(path);
+      expect(result).toEqual('/docs/api/core/sub/symbol');
+    });
+  });
+
+  describe('for a package guide path', () => {
+    it('should return a package link', () => {
+      const path = '/libs/core/guides/test/guide.md';
+      const result = daffDocsGetLinkUrl(path);
+      expect(result).toEqual('/docs/packages/core/test/guide');
+    });
+  });
+
+  describe('for a global guide path', () => {
+    it('should return a guide link', () => {
+      const path = '/docs/guides/test/guide.md';
+      const result = daffDocsGetLinkUrl(path);
+      expect(result).toEqual('/docs/guides/test/guide');
+    });
+  });
+
+  describe('for a global explanation path', () => {
+    it('should return an explanation link', () => {
+      const path = '/docs/explanations/test/guide.md';
+      const result = daffDocsGetLinkUrl(path);
+      expect(result).toEqual('/docs/explanations/test/guide');
+    });
+  });
+});

libs/docs-utils/src/kind/helpers.ts

@@ -0,0 +1,46 @@
+import { DaffDocKind } from './enum';
+import { DAFF_DOC_KIND_PATH_SEGMENT_MAP } from './path-segment-map';
+
+const DOC_KIND_REGEX = {
+  [DaffDocKind.GUIDE]: /\/docs\/guides\/(?<path>.+)\.md/,
+  [DaffDocKind.EXPLANATION]: /\/docs\/explanations\/(?<path>.+)\.md/,
+  [DaffDocKind.PACKAGE]: /\/libs\/(?<path>.+)\.md/,
+  [DaffDocKind.API]: /\/libs\/(?<path>.+)\.ts/,
+};
+
+/**
+ * Returns the kind of document based on the passed filepath.
+ *
+ * @param path the file path relative to the project root.
+ */
+export const daffDocsGetKind = (path: string): string => (<Array<keyof typeof DOC_KIND_REGEX>>Object.keys(DOC_KIND_REGEX)).find((k) => DOC_KIND_REGEX[k].test(path));
+
+/**
+ * Returns the URL that links to the document referenced by the passed path.
+ *
+ * @param path the file path relative to the project root.
+ */
+// TODO: combine with path generation logic in the creation of docs own paths
+export const daffDocsGetLinkUrl = (path: string): string => {
+  const kind = daffDocsGetKind(path);
+  const match = DOC_KIND_REGEX[kind]?.exec(path);
+
+  if (!match) {
+    return path;
+  }
+
+  const matchPath = match.groups.path.replaceAll(/\/(?:readme|src|guides)/gi, '');
+
+  switch (kind) {
+    case DaffDocKind.GUIDE:
+    case DaffDocKind.EXPLANATION:
+    case DaffDocKind.API:
+      return `/docs/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[kind]}/${matchPath}`;
+
+    case DaffDocKind.PACKAGE:
+      return `/docs/packages/${matchPath}`;
+
+    default:
+      return path;
+  }
+};

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

@@ -1,2 +1,3 @@
 export * from './enum';
 export * from './path-segment-map';
+export * from './helpers';

tools/dgeni/src/processors/markdown.ts

@@ -12,10 +12,7 @@ import { slugify } from 'markdown-toc';
 import { marked } from 'marked';
 import { markedHighlight } from 'marked-highlight';
 
-import {
-  DAFF_DOC_KIND_PATH_SEGMENT_MAP,
-  DaffDocKind,
-} from '@daffodil/docs-utils';
+import { daffDocsGetLinkUrl } from '@daffodil/docs-utils';
 
 import { CollectLinkableSymbolsProcessor } from './collect-linkable-symbols';
 
@@ -27,34 +24,6 @@ hljs.registerLanguage('bash', bash);
 hljs.registerLanguage('graphql', graphql);
 hljs.registerLanguage('gql', graphql);
 
-const DOC_KIND_REGEX = {
-  [DaffDocKind.GUIDE]: /\/docs\/guides\/(?<path>.+)\.md/,
-  [DaffDocKind.EXPLANATION]: /\/docs\/explanations\/(?<path>.+)\.md/,
-  [DaffDocKind.PACKAGE]: /\/libs\/(?<path>.+)\.md/,
-  [DaffDocKind.API]: /\/libs\/(?<path>.+)\.ts/,
-};
-const getLinkUrl = (path: string): string => {
-  const kind = (<Array<keyof typeof DOC_KIND_REGEX>>Object.keys(DOC_KIND_REGEX)).find((k) => DOC_KIND_REGEX[k].test(path));
-  const match = DOC_KIND_REGEX[kind]?.exec(path);
-
-  if (!match) {
-    return path;
-  }
-
-  switch (kind) {
-    case DaffDocKind.GUIDE:
-    case DaffDocKind.EXPLANATION:
-    case DaffDocKind.API:
-      return `/docs/${DAFF_DOC_KIND_PATH_SEGMENT_MAP[kind]}/${match.groups.path}`;
-
-    case DaffDocKind.PACKAGE:
-      return `/docs/packages/${match.groups.path}`.replaceAll(/\/(?:readme|src|guides)/gi, '');
-
-    default:
-      return path;
-  }
-};
-
 // marked.use(markedMermaid);
 marked.use(
   markedHighlight({
@@ -70,7 +39,7 @@ marked.use({
   walkTokens: (token) => {
     switch (token.type) {
       case 'link':
-        token.href = getLinkUrl(token.href);
+        token.href = daffDocsGetLinkUrl(token.href);
         break;
 
       default: