Host typedoc on netlify #707

Author: joepio

CONTRIBUTE.md

@@ -1,4 +1,4 @@
-# Guide for Atomic Data Rust contributors
+# Guide for Atomic-Server contributors
 
 First things first: I'm glad you're reading this!
 Join our [Discord](https://discord.gg/a72Rv2P) to chat with other people in the Atomic Data community.
@@ -13,16 +13,17 @@ Check out the [Roadmap](https://docs.atomicdata.dev/roadmap.html) if you want to
 ## Table of contents
 
 - [Table of contents](#table-of-contents)
-- [Running locally](#running-locally)
-- [Running locally (with local development browser)](#running-locally-with-local-development-browser)
-- [Compilation using Earthly](#compilation-using-earthly)
-- [Improve local compilation speed](#improve-local-compilation-speed)
-- [Cross compilation](#cross-compilation)
-- [IDE setup (VSCode)](#ide-setup-vscode)
-- [Branching](#branching)
+- [Running \& compiling](#running--compiling)
+  - [Running locally (with local development browser)](#running-locally-with-local-development-browser)
+  - [Debugging](#debugging)
+  - [IDE setup (VSCode)](#ide-setup-vscode)
+  - [Compilation using Earthly](#compilation-using-earthly)
+  - [Improve local compilation speed](#improve-local-compilation-speed)
+  - [Cross compilation](#cross-compilation)
+- [Git policy](#git-policy)
+  - [Open a PR](#open-a-pr)
+  - [Branching](#branching)
 - [Testing](#testing)
-- [Code coverage](#code-coverage)
-- [Debugging](#debugging)
 - [Performance monitoring / benchmarks](#performance-monitoring--benchmarks)
   - [Tracing](#tracing)
     - [Tracing with OpenTelemetry (and Jaeger)](#tracing-with-opentelemetry-and-jaeger)
@@ -31,25 +32,36 @@ Check out the [Roadmap](https://docs.atomicdata.dev/roadmap.html) if you want to
   - [Drill](#drill)
 - [Responsible disclosure / Coordinated Vulnerability Disclosure](#responsible-disclosure--coordinated-vulnerability-disclosure)
 - [Releases, Versioning and Tagging](#releases-versioning-and-tagging)
+  - [CI situation](#ci-situation)
   - [Publishing manually - doing the CI's work](#publishing-manually---doing-the-cis-work)
     - [Building and publishing binaries](#building-and-publishing-binaries)
     - [Publishing to Cargo](#publishing-to-cargo)
     - [Publishing server to Docker](#publishing-server-to-docker)
     - [Deploying to atomicdata.dev](#deploying-to-atomicdatadev)
     - [Publishing atomic-cli to WAPM](#publishing-atomic-cli-to-wapm)
 
-## Running locally
+## Running & compiling
 
-Clone the repo and run `cargo run` from each folder (e.g. `cli` or `server`).
+TL;DR Clone the repo and run `cargo run` from each folder (e.g. `cli` or `server`).
 
-## Running locally (with local development browser)
+### Running locally (with local development browser)
 
 - Run `cargo run` to start the server
 - Go to `browser`, run `pnpm install` (if you haven't already), and run `pnpm dev` to start the browser
 - Visit your `localhost` in your locally running `atomic-data-browser` instance: (e.g. `http://localhost:5173/app/show?subject=http%3A%2F%2Flocalhost`)
-- use `cargo watch -- cargo run` to automatically recompile `atomic-server` when you push new assets using `pmpm build-server` in `atomic-data-browser`. This can be useful if you're debugging specific features that you can't reproduce while the front-end is hosted in vite.
+- use `cargo watch -- cargo run` to automatically recompile `atomic-server` when you update JS assets in `browser`
 
-## Compilation using Earthly
+### Debugging
+
+- **VSCode Users**: Install the `CodeLLDB` plugin, and press F5 to start debugging. Breakpoints, inspect... The good stuff.
+
+### IDE setup (VSCode)
+
+This project is primarily being developed in VSCode.
+That doesn't mean that you should, too, but it means you're less likely to run into issues.
+The `/.vscode` directory contains various tasks, recommended extensions, and some settings overwrites.
+
+### Compilation using Earthly
 
 There are `earthfile`s in `browser` and in `atomic-server`.
 These can be used by Earthly to build all steps, including a full docker image.
@@ -58,12 +70,12 @@ These can be used by Earthly to build all steps, including a full docker image.
 - `earthly --org ontola -P --satellite henk --artifact +e2e/test-results +pipeline`
 - `earthly --org ontola -P --satellite henk --artifact +build-server/atomic-server ./output/atomicserver`
 
-## Improve local compilation speed
+### Improve local compilation speed
 
 - Use the [`mold`](https://github.com/rui314/mold) linker + create a `.cargo/config.toml` and add `[build] rustflags = ["-C", "link-arg=-fuse-ld=lld"]`
 - Note: this is primarily for development on linux systems, as mold for macOS requires a paid license
 
-## Cross compilation
+### Cross compilation
 
 If you want to build `atomic-server` for some other target (e.g. building for linux from macOS), you can use the `cross` crate.
 
@@ -73,21 +85,20 @@ cargo install cross
 cross build --target x86_64-unknown-linux-musl --bin atomic-server --release
 ```
 
+## Git policy
 
-## IDE setup (VSCode)
+### Open a PR
 
-This project is primarily being developed in VSCode.
-That doesn't mean that you should, too, but it means you're less likely to run into issues.
-The `/.vscode` directory contains various tasks, recommended extensions, and some settings overwrites.
+- Make sure your branch is up to date with `develop`.
+- Open a PR against `develop`.
+- Make sure all relevant tests / lint pass.
 
-## Branching
+### Branching
 
 Create new branches off `develop`. When an issue is ready for PR, open PR against `develop`.
 
 ## Testing
 
-- All tests are run in CI
-
 ```sh
 # Make sure nextest is installed
 cargo install cargo-nextest
@@ -102,9 +113,12 @@ cargo run
 # now, open new terminal window
 cd server/e2e_tests/ && npm i && npm run test
 # if things go wrong, debug!
-npm run test-query {testname}
+pnpm run test-query {testname}
 ```
 
+<!--
+NOTE: NOT WORKING SINCE EARHTLY
+
 ## Code coverage
 
 - Visible at https://app.codecov.io/gh/atomicdata-dev/atomic-server/
@@ -114,11 +128,7 @@ npm run test-query {testname}
 # install cargo-llvm-cov, see https://github.com/taiki-e/cargo-llvm-cov
 # Run the tests with a coverage report
 cargo llvm-cov --all-features --show-missing-lines
-```
-
-## Debugging
-
-- **VSCode Users**: Install the `CodeLLDB` plugin, and press F5 to start debugging. Breakpoints, inspect... The good stuff.
+``` -->
 
 ## Performance monitoring / benchmarks
 
@@ -204,6 +214,11 @@ Note:
 - The version for `atomic-lib` is the most important, and dictates the versions of `cli` and `server`. When `lib` changes minor version, `cli` and `server` should follow.
 - After publishing, update the `./desktop/latest-version.json` file. This is used for auto-updating desktop distributions. See [tauri docs](https://tauri.studio/docs/distribution/updater).
 
+### CI situation
+
+- Github Action for `push`: builds + tests + docker (using `earthly`, see `Earthfile`)
+- Github Action for `tag`: create release + publish binaries
+
 ### Publishing manually - doing the CI's work
 
 If the CI scripts for some reason do not do their job (buildin releases, docker file, publishing to cargo), you can follow these instructions:

README.md

@@ -408,7 +408,7 @@ Front-end for Atomic-Server, built with React.
 
 Library with `Store`, `Commit`, `JSON-AD` parsing, and more.
 
-[**docs**](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules/_tomic_lib.html)
+[**docs**](https://atomic-lib.netlify.app/modules/_tomic_lib)
 
 ### [`@tomic/react`](browser/react/README.md)
 
@@ -424,7 +424,7 @@ Library with `Store`, `Commit`, `JSON-AD` parsing, and more.
 
 React library with many useful hooks for rendering and editing Atomic Data.
 
-[**docs**](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules/_tomic_react.html)
+[**docs**](https://atomic-lib.netlify.app/modules/_tomic_react)
 
 ## Also check out
 

browser/DOCS.MD

@@ -1,5 +1,7 @@
 ## Atomic Data Typescript (@tomic) Docs
 
-Documentation for `@tomic/lib` and `@tomic/react`.
+Documentation for [`@tomic/lib`](/modules/_tomic_lib) and [`@tomic/react`](/modules/_tomic_react).
+
+Hosted on [atomic-lib.netlify.app](https://atomic-lib.netlify.app/)
 
 See [the Github repository](https://github.com/atomicdata-dev/atomic-data-browser) for more information and issues.

browser/Earthfile

@@ -3,20 +3,11 @@ PROJECT ontola/atomic-server
 FROM node:20.8.0-bookworm
 WORKDIR browser
 
-pipeline:
-  PIPELINE --push
-  TRIGGER push develop
-  TRIGGER push main
-  TRIGGER pr develop
-  ARG tag=latest
-  BUILD +test
-  BUILD +lint
-  BUILD +build --tag=$tag
-
 all:
   BUILD +build
   BUILD +test
   BUILD +lint
+  BUILD +typedoc
 
 deps:
   RUN curl -f https://get.pnpm.io/v6.14.js | node - add --global pnpm
@@ -41,3 +32,7 @@ build:
   FROM +deps
   RUN pnpm run build
   SAVE ARTIFACT ./data-browser/dist
+
+typedoc:
+  FROM +build
+  RUN --secret NETLIFY_AUTH_TOKEN=NETLIFY_TOKEN pnpm run typedoc-publish

browser/README.md

@@ -38,7 +38,7 @@ pnpm start # run the server!
 
 Library with `Store`, `Commit`, `JSON-AD` parsing, and more.
 
-[**docs**](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules/_tomic_lib.html)
+[**docs**](https://atomic-lib.netlify.app/modules/_tomic_lib)
 
 [→ Read more](lib/README.md)
 
@@ -59,7 +59,7 @@ React library with many useful hooks for rendering and editing Atomic Data.
 
 [**demo + template on codesandbox**](https://codesandbox.io/s/atomic-data-react-template-4y9qu?file=/src/MyResource.tsx:0-1223)
 
-[**docs**](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules/_tomic_react.html)
+[**docs**](https://atomic-lib.netlify.app/modules/_tomic_react)
 
 [→ Read more](react/README.md)
 

browser/lib/README.md

@@ -1,5 +1,5 @@
 # @tomic/lib: The Atomic Data library for typescript / javascript
 
-[**docs**](https://atomicdata-dev.github.io/atomic-data-browser/docs/modules/_tomic_lib.html)
+[**docs**](https://atomic-lib.netlify.app/modules/_tomic_lib)
 
 Core typescript library for handling JSON-AD parsing, storing [Atomic Data](https://docs.atomicdata.dev/), signing Commits, and more.

browser/lib/package.json

@@ -1,5 +1,4 @@
 {
-  "version": "0.36.0",
   "author": "Joep Meindertsma",
   "dependencies": {
     "@noble/ed25519": "1.6.0",
@@ -10,36 +9,37 @@
   },
   "description": "",
   "devDependencies": {
+    "@tomic/cli": "workspace:*",
     "@types/fast-json-stable-stringify": "^2.1.0",
     "chai": "^4.3.4",
     "typescript": "^4.8",
-    "whatwg-fetch": "^3.6.2",
-    "@tomic/cli": "workspace:*"
+    "whatwg-fetch": "^3.6.2"
   },
   "files": [
     "dist"
   ],
+  "gitHead": "2172c73d8df4e5f273e6386676abc91b6c5b2707",
   "license": "MIT",
-  "main-dev": "src/index.ts",
   "main": "dist/src/index.js",
+  "main-dev": "src/index.ts",
   "name": "@tomic/lib",
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
     "build": "tsc",
+    "generate-ontologies": "ad-generate ontologies",
     "lint": "eslint ./src --ext .js,.jsx,.ts,.tsx",
     "lint-fix": "eslint ./src --ext .js,.jsx,.ts,.tsx --fix",
     "prepublishOnly": "pnpm run build && pnpm run lint-fix",
-    "watch": "tsc --build --watch",
     "start": "pnpm watch",
     "test": "NODE_OPTIONS='--experimental-vm-modules' ../node_modules/jest/bin/jest.js",
     "tsc": "tsc --build",
     "typecheck": "tsc --noEmit",
-    "generate-ontologies": "ad-generate ontologies"
+    "watch": "tsc --build --watch"
   },
   "source": "src/index.ts",
   "type": "module",
   "types": "dist/src/index.d.ts",
-  "gitHead": "2172c73d8df4e5f273e6386676abc91b6c5b2707"
+  "version": "0.36.0"
 }

browser/package.json

@@ -20,6 +20,7 @@
     "eslint-plugin-react-hooks": "^4.3.0",
     "husky": "^8.0.3",
     "jest": "^29.0.2",
+    "netlify-cli": "16.2.0",
     "prettier": "2.4.1",
     "prettier-plugin-jsdoc": "^0.3.24",
     "react": "^18.2.0",
@@ -42,7 +43,8 @@
     "test-e2e": "pnpm run --filter @tomic/e2e test-e2e",
     "test-query": "pnpm run --filter @tomic/e2e test-query",
     "start": "pnpm run -r --parallel start",
-    "typedoc": "typedoc . --options typedoc.json",
+    "typedoc": "typedoc --options ./typedoc.json",
+    "typedoc-publish": "pnpm run typedoc && netlify deploy --dir data-browser/publish/docs/ --prod --auth $NETLIFY_AUTH_TOKEN --site atomic-lib",
     "typecheck": "pnpm run -r --parallel typecheck"
   },
   "husky": {