feat: typedoc cli packages

.github/workflows/build_dart.yaml

@@ -0,0 +1,94 @@
+name: build_dart
+
+on:
+  pull_request:
+  push:
+    branches:
+      - typedoc-cli
+      - main
+
+jobs:
+  build_linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1
+
+      - name: Install dependencies
+        working-directory: packages/dart_cli
+        run: dart pub get
+
+      - name: Compiling
+        working-directory: packages/dart_cli
+        run: dart compile exe bin/docs_page.dart -o docs_page
+
+      - name: Store binary
+        uses: actions/upload-artifact@v3
+        with:
+          name: linux-binary
+          path: packages/dart_cli/docs_page
+
+  build_macos:
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1
+
+      - name: Install dependencies
+        working-directory: packages/dart_cli
+        run: dart pub get
+
+      - name: Compiling
+        working-directory: packages/dart_cli
+        run: dart compile exe bin/docs_page.dart -o docs_page
+
+      - name: Store binary
+        uses: actions/upload-artifact@v3
+        with:
+          name: macos-binary
+          path: packages/dart_cli/docs_page
+
+  build_windows:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: dart-lang/setup-dart@v1
+
+      - name: Install dependencies
+        working-directory: packages/dart_cli
+        run: dart pub get
+
+      - name: Compiling
+        working-directory: packages/dart_cli
+        run: dart compile exe bin/docs_page.dart -o docs_page.exe
+
+      - name: Store binary
+        uses: actions/upload-artifact@v3
+        with:
+          name: windows-binary
+          path: packages/dart_cli/docs_page.exe
+
+  combine_outputs:
+    runs-on: ubuntu-latest
+    needs: [build_linux, build_macos, build_windows]
+    steps:
+      - name: Download linux artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: linux-binary
+          path: ~/binaries/linux
+      - name: Download macos artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: macos-binary
+          path: ~/binaries/darwin
+      - name: Download windows artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: windows-binary
+          path: ~/binaries/win32
+      - name: Store binaries
+        uses: actions/upload-artifact@v3
+        with:
+          name: binaries
+          path: ~/binaries

.prettierignore

@@ -5,4 +5,6 @@ dist
 repositories.json
 domains.json
 spelling.json
-_docs.page
+_docs.page
+packages/dart_cli/example
+packages/dart_cli/docs

api/src/controllers/raw.ts

@@ -14,7 +14,6 @@ export const bundleRaw = async (
   const path = (req?.query.path as string) || 'index';
   const headerDepth = req?.query?.headerDepth ? parseInt(req?.query?.headerDepth as string) : 3;
   const { md: markdown, config: sourceConfig } = req.body;
-
   const bundleInstance = new Bundle({
     owner: 'n/a',
     repository: 'n/a',

api/src/utils/bundle.ts

@@ -33,6 +33,12 @@ type BundleConstructorParams = {
   config?: OutputConfig;
 };
 
+export type References = {
+  name: string;
+  path: string;
+  kind: string;
+}[];
+
 export class Bundle {
   code: string;
   markdown: string;
@@ -48,6 +54,7 @@ export class Bundle {
   headerDepth: number;
   built: boolean;
   contentFetched: boolean;
+  referenceConfig: References | null;
 
   constructor({
     owner,
@@ -77,6 +84,7 @@ export class Bundle {
     this.sourceChecked = false;
     this.built = false;
     this.contentFetched = false;
+    this.referenceConfig = null;
   }
 
   // check for branch/PR ref
@@ -108,7 +116,7 @@ export class Bundle {
     }
     this.baseBranch = githubContents.baseBranch;
     this.repositoryFound = githubContents.repositoryFound;
-
+    this.referenceConfig = githubContents.referenceConfig;
     this.formatConfigLocales(githubContents.config);
     await this.matchSymLinks();
     if (githubContents.md === null) {
@@ -156,6 +164,7 @@ export class Bundle {
       repositoryFound: this.repositoryFound,
       source: this.source,
       ref: this.ref,
+      referenceConfig: this.referenceConfig,
     };
   }
 

api/src/utils/github.ts

@@ -1,6 +1,7 @@
 import A2A from 'a2a';
 import { graphql } from '@octokit/graphql';
 import dotenv from 'dotenv';
+import { References } from './bundle';
 dotenv.config();
 
 const getGitHubToken = (() => {
@@ -55,6 +56,9 @@ type PageContentsQuery = {
     mdxIndex?: {
       text: string;
     };
+    referenceConfig?: {
+      text: string;
+    };
   };
 };
 
@@ -69,6 +73,7 @@ export type Contents = {
   md: string | null;
   path: string;
   repositoryFound: boolean;
+  referenceConfig: References | null;
 };
 
 export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Promise<Contents> {
@@ -78,7 +83,7 @@ export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Pr
   const [error, response] = await A2A<PageContentsQuery>(
     getGithubGQLClient()({
       query: `
-      query RepositoryConfig($owner: String!, $repository: String!, $configJson: String!, $configYaml: String!, $configToml: String!, $mdx: String!, $mdxIndex: String!) {
+      query RepositoryConfig($owner: String!, $repository: String!, $configJson: String!, $configYaml: String!, $configToml: String!, $mdx: String!, $mdxIndex: String!, $referenceConfig: String!) {
         repository(owner: $owner, name: $repository) {
           baseBranch: defaultBranchRef {
             name
@@ -109,6 +114,11 @@ export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Pr
               text
             }
           }
+          referenceConfig: object(expression: $referenceConfig) {
+            ... on Blob {
+              text
+            }
+          }
         }
       }
     `,
@@ -119,6 +129,7 @@ export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Pr
       configToml: `${metadata.ref}:docs.toml`,
       mdx: `${metadata.ref}:${absolutePath}.mdx`,
       mdxIndex: `${metadata.ref}:${indexPath}.mdx`,
+      referenceConfig: `${metadata.ref}:docs.refs.json`,
     }),
   );
 
@@ -130,6 +141,16 @@ export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Pr
     };
   }
 
+  let referenceConfig = null;
+  try {
+    referenceConfig = response?.repository.referenceConfig?.text
+      ? JSON.parse(response?.repository.referenceConfig?.text)
+      : null;
+  } catch (e) {
+    console.error('Could not parse reference config');
+    console.error(e);
+  }
+
   return {
     repositoryFound: true,
     isFork: response?.repository?.isFork ?? false,
@@ -141,6 +162,7 @@ export async function getGitHubContents(metadata: MetaData, noDir?: boolean): Pr
     },
     md: response?.repository.mdxIndex?.text || response?.repository.mdx?.text || null,
     path: response?.repository.mdxIndex?.text ? indexPath : absolutePath,
+    referenceConfig,
   };
 }
 

docs/typedoc.mdx

@@ -0,0 +1,28 @@
+---
+title: Typedoc Support
+description: Learn how to generate docs.page references using typedoc comments
+---
+
+# Typedoc Support
+
+If you've added typedoc-compliant comments to your code, Docs.page is able to generate reference pages from your typedoc.json.
+
+The steps are as follows:
+
+1. In your root directory, generate your `typedoc.json` from your code, using the flag `--json`, and specifying your output path as `docs/typedoc.json`. You will have to install typedoc first, and the command should look similar to:
+
+```
+npm run typedoc --json docs/typedoc.json src/index.ts
+```
+
+or if you're using yarn,
+
+```
+yarn typedoc --json docs/typedoc.json src/index.ts
+```
+
+2. Add a `references` field to your `docs.json` or `docs.yaml` configuration file. This value specifies the folder in which your references will be generated. If you're unsure, set it as `Reference` or `API`.
+3. Add a `typedocEntryDir` field to your `docs.json` or `docs.yaml` configuration file. This should be set as the path of the directory where your typedoc entry file is.
+4. Run
+   `docs_page typedoc`
+   from your root directory.

packages/dart_cli/.gitignore

@@ -7,4 +7,5 @@ build/
 
 # Created by running the command in this directory, don't commit
 docs.yaml
-docs
+docs
+docs_page

packages/dart_cli/CHANGELOG.md

@@ -1,3 +1,11 @@
-## 1.0.0
+## 0.0.1
 
-- Initial version.
+- prerelease version.
+
+## 0.0.2
+
+- added `help` command and made `init` command more user-friendly
+
+## 0.0.3
+
+- fix check for `docs.refs.json` on `typedoc` command