🦄 feature: Better docs for API etc.

.husky/pre-commit

@@ -0,0 +1,3 @@
+node ./scripts/build-docs.mjs
+git add -A
+

README.md

@@ -33,7 +33,7 @@ on:
       - main
 jobs:
   previews:
-    name: '🔮 Previews'
+    name: "🔮 Previews"
     runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'preview')
     steps:
@@ -50,7 +50,32 @@ jobs:
 
 ## API Documentation
 
-TBD
+<!-- docs:start -->
+### Inputs
+
+| Field | Required | Description | Default |
+| ----- | -------- | ----------- | ------- |
+| name | yes | The name of the service (must be unique) to be deployed. | - |
+| port | no | The port that the application will run on in the container. | 8080 |
+| env_vars | no | List of environment variables that will be injected during runtime, each on a new line. | - |
+| secrets | no | List of secrets that will be injected during runtime, each on a new line. | - |
+| flags | no | List of flags that will be injected during runtime. | - |
+| gcp_region | yes | The GCP Region where the service will be deployed. | us-central1 |
+| gcp_project_id | yes | The GCP Project ID where the service will be deployed. | - |
+| gcp_service_account_key | yes | The Service Account JSON Key used to push images to the GCP Artifact Registry. | - |
+| gcp_artifact_repository | yes | The Artifact Registry name, you can override for custom names (i.e. the 'acme' in us-docker.pkg.dev/able-sailor-21423/acme) | - |
+| github_token | yes | Github Token, pass in the `secrets.GITHUB_TOKEN`. | - |
+| docker_file_name | yes | The Dockerfile name, you can override for custom names (i.e. DevDockerfile) | Dockerfile |
+| docker_directory | yes | Directory where the DockerFile is located. | . |
+| docker_build_args | no | Comma separated list of arguments that will be injected during the build, each on a new line. | - |
+
+### Outputs
+
+| Field | Description |
+| ----- | ----------- |
+| url | The preview URL for the running application |
+
+<!-- docs:end -->
 
 ## Examples
 
@@ -69,7 +94,7 @@ on:
 
 jobs:
   previews:
-    name: '🔮 Previews'
+    name: "🔮 Previews"
     runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'preview')
     steps:
@@ -135,7 +160,7 @@ on:
 
 jobs:
   previews:
-    name: '🔮 Previews'
+    name: "🔮 Previews"
     runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'preview')
     steps:
@@ -171,7 +196,7 @@ on:
 
 jobs:
   previews:
-    name: '🔮 Previews'
+    name: "🔮 Previews"
     runs-on: ubuntu-latest
     if: contains(github.event.pull_request.labels.*.name, 'preview')
     steps:

package.json

@@ -4,5 +4,13 @@
   "private": true,
   "workspaces": [
     "packages/*"
-  ]
+  ],
+  "devDependencies": {
+    "@joggr/tempo": "^0.6.0",
+    "husky": "^9.0.11",
+    "yaml": "^2.3.4"
+  },
+  "scripts": {
+    "prepare": "husky"
+  }
 }

scripts/build-docs.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import tempo from '@joggr/tempo';
+import YAML from 'yaml';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const FILEPATH_README = path.resolve(__dirname, path.join('..', 'README.md'));
+const FILEPATH_ACTION_CONFIG = path.resolve(__dirname, path.join('..', 'action.yaml'));
+
+const COMMENT_START = '<!-- docs:start -->';
+const COMMENT_END = '<!-- docs:end -->';
+
+const run = () => {
+  process.stdout.write('📚 Building docs...\n');
+  try {
+    const actionYaml = fs.readFileSync(FILEPATH_ACTION_CONFIG, 'utf8');
+    const parsedActionYaml = YAML.parse(actionYaml);
+
+    const inputs = [];
+    const outputs = [];
+
+    for (const [key, value] of Object.entries(parsedActionYaml.inputs)) {
+      const def = key !== 'gcp_project_id' ? value.default : '-';
+      inputs.push([key, value.required ? 'yes' : 'no', value.description ?? 'no description provided', def ?? '-']);
+    }
+
+    for (const [key, value] of Object.entries(parsedActionYaml.outputs)) {
+      outputs.push([key, value.description ?? 'no description provided']);
+    }
+
+    const api = tempo.default()
+      .h3('Inputs')
+      .table([
+        ['Field', 'Required', 'Description', 'Default'],
+        ...inputs,
+      ])
+      .h3('Outputs')
+      .table([
+        ['Field', 'Description'],
+        ...outputs,
+      ])
+      .toString();
+
+    const readme = fs.readFileSync(FILEPATH_README, 'utf8');
+    const splitReadme = readme.split(COMMENT_START);
+    const splitReadmeEnd = splitReadme[1].split(COMMENT_END);
+    const newReadme = `${splitReadme[0]}${COMMENT_START}\n${api}\n${COMMENT_END}${splitReadmeEnd[1]}`;
+
+    // Write the new README
+    fs.writeFileSync(FILEPATH_README, newReadme);
+
+    process.stdout.write('✅ Completed Building Docs\n');
+  } catch (error) {
+    process.stderr.write(`❌ Error: ${error.message}\n`);
+    process.exit(1);
+  }
+};
+run();

yarn.lock

@@ -38,6 +38,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@joggr/tempo@npm:^0.6.0":
+  version: 0.6.0
+  resolution: "@joggr/tempo@npm:0.6.0"
+  checksum: 10c0/75cd9588d3e8880cc41c055a947d91868a04ec55eb96ce5b637fc229634cac210a504e1bd08b56272c1c74bd7312b908f0cf51c60c88ecf2e4e7131f60fa2c05
+  languageName: node
+  linkType: hard
+
 "@protobufjs/aspromise@npm:^1.1.1, @protobufjs/aspromise@npm:^1.1.2":
   version: 1.1.2
   resolution: "@protobufjs/aspromise@npm:1.1.2"
@@ -490,6 +497,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"husky@npm:^9.0.11":
+  version: 9.0.11
+  resolution: "husky@npm:9.0.11"
+  bin:
+    husky: bin.mjs
+  checksum: 10c0/2c787dcf74a837fc9a4fea7da907509d4bd9a289f4ea10ecc9d86279e4d4542b0f5f6443a619bccae19e265f2677172cc2b86aae5c932a35a330cc227d914605
+  languageName: node
+  linkType: hard
+
 "ieee754@npm:^1.2.1":
   version: 1.2.1
   resolution: "ieee754@npm:1.2.1"
@@ -663,6 +679,10 @@ __metadata:
 "previews@workspace:.":
   version: 0.0.0-use.local
   resolution: "previews@workspace:."
+  dependencies:
+    "@joggr/tempo": "npm:^0.6.0"
+    husky: "npm:^9.0.11"
+    yaml: "npm:^2.3.4"
   languageName: unknown
   linkType: soft
 
@@ -981,6 +1001,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"yaml@npm:^2.3.4":
+  version: 2.3.4
+  resolution: "yaml@npm:2.3.4"
+  checksum: 10c0/cf03b68f8fef5e8516b0f0b54edaf2459f1648317fc6210391cf606d247e678b449382f4bd01f77392538429e306c7cba8ff46ff6b37cac4de9a76aff33bd9e1
+  languageName: node
+  linkType: hard
+
 "yargs-parser@npm:^21.1.1":
   version: 21.1.1
   resolution: "yargs-parser@npm:21.1.1"