Merge pull request #6 from AI-ASMR/typedoc

Typedoc CI/CD

.dockerignore

@@ -2,4 +2,5 @@ node_modules
 tensorboard/**
 Dockerfile
 .pre
-.out
+.out
+docs

.github/workflows/publish-docs.yml

@@ -0,0 +1,39 @@
+name: Docs publish
+
+permissions: write-all
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'version.cfg'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        # We need to use PAT alongside this
+        # see: https://github.com/orgs/community/discussions/26220
+        persist-credentials: false
+
+    - name: Setup Node.js
+      uses: actions/setup-node@v2
+      with:
+        node-version: '18.19.0'
+
+    - name: Configure Git
+      run: |
+        git config user.email "${{ github.actor }}@users.noreply.github.com"
+        git config user.name "${{ github.actor }}"
+
+    - name: Install dependencies
+      run: npm ci
+
+    - name: Publish the new version
+      env:
+        GITHUB_TOKEN: ${{ secrets.PAT }}
+      run: npm run publish.docs

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 .pre
 .out
-tensorboard/**
+tensorboard/**
+docs

README.md

@@ -24,7 +24,7 @@ This is an all-in-one repository that holds the source code for both the trainin
 
 ### Model architecture. <a id="model"></a>
 
-<img src="https://i.imgur.com/F0XZWjJ.png">
+<img src="./assets/model.png">
 
 ### Getting started. <a id="getting-started"></a>
 

lib/typedoc.json

@@ -0,0 +1,4 @@
+{
+    "extends": ["../typedoc.base.json"],
+    "entryPoints": ["./index.ts"]
+}

package.json

@@ -4,11 +4,11 @@
     "description": "",
     "scripts": {
         "preinstall": "node ./scripts.js --prepare.lib --prepare.bin",
+        "build.docs": "node ./scripts.js --build.docs",
+        "publish.docs": "node ./scripts.js --publish.docs",
         "build.lib": "node ./scripts.js --build.lib",
         "publish.lib": "node ./scripts.js --publish.lib",
         "build.bin": "node ./scripts.js --build.bin",
-        "docs.lib": "node ./scripts.js --docs.lib",
-        "docs.bin": "node ./scripts.js --docs.bin",
         "test.lib": "node ./scripts.js --test.lib",
         "test.bin": "node ./scripts.js --test.bin",
         "lint.all": "node ./scripts.js --lint.all",
@@ -26,6 +26,7 @@
         "@typescript-eslint/eslint-plugin": "^6.13.2",
         "@typescript-eslint/parser": "^6.13.2",
         "eslint": "^8.55.0",
+        "typedoc": "^0.25.4",
         "typescript": "^5.3.3"
     },
     "engines": {

scripts.js

@@ -378,12 +378,50 @@ registerCommand('run.bin', () => {
     exec(`npx tsx ./.pre/index.ts --tsconfig ./dev.tsconfig.json ${args}`, { cwd: './src' });
 }, true /* Don't print to stdout as we're running the binary. */);
 
-registerCommand('docs.lib', () => {
-    console.log('todo');
+/**
+ * @summary
+ * Build docs using typedoc via monorepo packages.
+ * 
+ * @example `npm run build.docs`
+ */
+registerCommand('build.docs', () => {
+    console.log('Building docs...');
+    exec('npx typedoc');
 });
 
-registerCommand('docs.bin', () => {
-    console.log('todo');
+/**
+ * @summary
+ * All in one command to build and publish the docs to
+ * the `docs` branch which is where github pages point to.
+ * 
+ * @note CI/CD runs this on every version bump. @see registerCommand('inc.ver')
+ * 
+ * @see '.github\workflows\publish-docs.yml'
+ */
+registerCommand('publish.docs', () => {
+    // clean the docs branch
+    exec('git checkout docs');
+    exec('git rm -f ./docs');
+    exec('git checkout main');
+
+    executeCommand('build.docs');
+
+    // copy over markdown assets
+    for(const file of fs.readdirSync('./assets'))
+        fs.copyFileSync(`./assets/${file}`, `./docs/assets/${file}`);
+
+    exec('git checkout docs');
+    exec('git add ./docs -f');
+    exec('git commit -m "docs: update"');
+
+    // ci/cd
+    if(process.env.GITHUB_TOKEN) {
+        exec(`git push https://${process.env.GITHUB_TOKEN}@github.com/AI-ASMR/asmr-gan-core.git docs`);
+    }
+    // manual/local
+    else {
+        exec('git push origin docs');
+    }
 });
 
 registerCommand('test.lib', () => {

src/typedoc.json

@@ -0,0 +1,6 @@
+{
+    "extends": ["../typedoc.base.json"],
+    "entryPoints": ["./*.ts"],
+    "excludeNotDocumented": true,
+    "exclude": ["./index.ts"]
+}

typedoc.base.json

@@ -0,0 +1,5 @@
+{
+    "$schema": "https://typedoc.org/schema.json",
+    "includeVersion": false,
+    "readme": "none"
+}

typedoc.json

@@ -0,0 +1,6 @@
+{
+    "entryPoints": ["./lib", "./src"],
+    "name": "AiMR's Model Training",
+    "entryPointStrategy": "packages",
+    "includeVersion": false,
+}