docs(docs): Add targets to make it easy to locally preview docs. (#1098)

* docs(docs): Add targets to make it easy to locally preview the documentation of the repo. * ci(general): Bump cat-ci version * fix(docs): Spelling * Update utilities/docs-preview/justfile Co-authored-by: bkioshn <[email protected]> --------- Co-authored-by: bkioshn <[email protected]>
input-output-hk · Nov 1, 2024 · ad71131 · ad71131
1 parent 5a14f87
commit ad71131
Show file tree

Hide file tree

Showing 14 changed files with 74 additions and 20 deletions.
diff --git a/.config/dictionaries/project.dic b/.config/dictionaries/project.dic
@@ -124,6 +124,7 @@ Jörmungandr
 jsonschema
 junitreport
 junitxml
+Justfile
 keychains
 Keyhash
 keyserver

diff --git a/Earthfile b/Earthfile
@@ -1,8 +1,8 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.2.21 AS mdlint-ci
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.2.21 AS cspell-ci
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/postgresql:v3.2.21 AS postgresql-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/mdlint:v3.2.22 AS mdlint-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/cspell:v3.2.22 AS cspell-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/postgresql:v3.2.22 AS postgresql-ci
 
 FROM debian:stable-slim
 

diff --git a/catalyst-gateway/Earthfile b/catalyst-gateway/Earthfile
@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/rust:v3.2.21 AS rust-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/rust:v3.2.22 AS rust-ci
 
 #cspell: words rustfmt toolsets USERARCH stdcfgs
 

diff --git a/catalyst-gateway/event-db/Earthfile b/catalyst-gateway/event-db/Earthfile
@@ -3,7 +3,7 @@
 # the database and its associated software.
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/postgresql:v3.2.21 AS postgresql-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/postgresql:v3.2.22 AS postgresql-ci
 
 # cspell: words
 

diff --git a/catalyst-gateway/tests/Earthfile b/catalyst-gateway/tests/Earthfile
@@ -1,5 +1,5 @@
 VERSION 0.8
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/spectral:v3.2.21 AS spectral-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/spectral:v3.2.22 AS spectral-ci
 
 # cspell: words oapi
 # test-lint-openapi - OpenAPI linting from an artifact

diff --git a/catalyst-gateway/tests/api_tests/Earthfile b/catalyst-gateway/tests/api_tests/Earthfile
@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.2.21 AS python-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/python:v3.2.22 AS python-ci
 
 builder:
     FROM python-ci+python-base

diff --git a/catalyst_voices/Earthfile b/catalyst_voices/Earthfile
@@ -1,7 +1,7 @@
 VERSION 0.8
 
 IMPORT ../catalyst-gateway AS catalyst-gateway
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.21 AS flutter-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.22 AS flutter-ci
 
 # Copy all the necessary files and running bootstrap
 builder:

diff --git a/catalyst_voices/uikit_example/Earthfile b/catalyst_voices/uikit_example/Earthfile
@@ -1,7 +1,7 @@
 VERSION 0.8
 
 IMPORT ../ AS catalyst-voices
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.21 AS flutter-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.22 AS flutter-ci
 
 # local-build-web - build web version of UIKit example.
 # Prefixed by "local" to make sure it's not auto triggered, the target was

diff --git a/catalyst_voices_packages/catalyst_cardano/catalyst_cardano/wallet-automation/Earthfile b/catalyst_voices_packages/catalyst_cardano/catalyst_cardano/wallet-automation/Earthfile
@@ -1,6 +1,6 @@
 VERSION 0.8
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.21 AS flutter-ci
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/playwright:v3.2.21 AS playwright-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/flutter:v3.2.22 AS flutter-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/playwright:v3.2.22 AS playwright-ci
 
 deps:
     DO playwright-ci+SETUP --workdir=/wallet-automation

diff --git a/docs/Earthfile b/docs/Earthfile
@@ -1,6 +1,6 @@
 VERSION 0.8
 
-IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.2.21 AS docs-ci
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.2.22 AS docs-ci
 
 IMPORT .. AS repo
 IMPORT ../catalyst-gateway AS catalyst-gateway
@@ -32,10 +32,7 @@ docs:
 #   --push will cause this image to be pushed to the local development cluster
 #   --local_registry : Set this to the hostname of your local registry or "" to inhibit.
 local:
-    # Change this to point to another local registry, OR set to "" to disable
-    # pushing to a local registry even if `--push` is passed.
-    # this should be "registry.cluster.test:5000" but Earthly can not reliably locate it in a hosts file.
-    ARG local_registry="192.168.58.10:5000"
+
     # ARG local_registry="registry.cluster.test"
     # Build a self contained service to show built docs locally.
     DO docs-ci+PACKAGE
@@ -45,8 +42,14 @@ local:
 
     # This is a local only image, we do not publish it.
     SAVE IMAGE cat-voices-docs:latest
+
+# registry-local: Local preview target - Pushed to a local registry
+registry-local:
+    FROM +local
+
+    # Change this to point to another local registry, OR set to "" to disable
+    # pushing to a local registry even if `--push` is passed.
+    # this should be "registry.cluster.test:5000" but Earthly can not reliably locate it in a hosts file.
+    ARG local_registry="192.168.58.10:5000"
 
-    # Publish to the local development cluster
-    IF [ "$local_registry" != "" ]
-        SAVE IMAGE --push --insecure $local_registry/cat-voices-docs:latest
-    END
+    SAVE IMAGE --push --insecure $local_registry/cat-voices-docs:latest
diff --git a/justfile b/justfile
@@ -28,3 +28,24 @@ run-cat-gateway:
 # Run cat-gateway natively on mainnet
 run-cat-gateway-mainnet: 
     just catalyst-gateway/run-cat-gateway-mainnet
+
+# Live rebuilds and deploys the documentation locally.
+preview-docs:
+    #
+    # Documentation get deployed to localhost:8280.
+    #
+    # Currently live rebuild is naive, it just re-runs the earthly docs build every 10 seconds.
+    # However, as earthly should cache most things on the first run, subsequent runs should only rebuild
+    # the parts that have changed.
+    # Deploys a nginx service using docker to port 8123, where a local version of the docs can be viewed.
+    #
+    # This target should be used by anyone updating code that will end up in the documentation to ensure
+    # it looks correct.  It is faster than using github actions to check for you.
+    #
+    # Tasks which will update the documentation (non-exhaustive):
+    #
+    # 1. Editing markdown files under docs/
+    # 2. Adding new markdown files under docs/
+    # 3. Updating rust code (rust docs are embedding in the documentation)
+    # 4. Updating Catalyst-Gateway OpenAPI endpoints (Published in the documentation)
+    just utilities/docs-preview/preview-docs
diff --git a/utilities/docs-preview/.gitignore b/utilities/docs-preview/.gitignore
@@ -0,0 +1 @@
+local.py
diff --git a/utilities/docs-preview/Earthfile b/utilities/docs-preview/Earthfile
@@ -0,0 +1,8 @@
+VERSION 0.8
+
+IMPORT github.com/input-output-hk/catalyst-ci/earthly/docs:v3.2.22 AS docs-ci
+
+
+# update-docs-dev-script: get the latest docs dev script from CI.
+update-docs-dev-script:
+    DO docs-ci+SYNC_LOCAL_DOCS
diff --git a/utilities/docs-preview/justfile b/utilities/docs-preview/justfile
@@ -0,0 +1,20 @@
+# use with https://github.com/casey/just
+#
+# Catalyst Voices Documentation Local Preview Build
+
+# cspell: words prereqs, commitlog
+
+default:
+    @just --list --unsorted
+
+# Ensure we have the latest version of the dev docs script locally.
+update-docs-dev-script:
+    earthly +update-docs-dev-script
+
+# Live rebuilds and deploys the documentation locally.
+#
+# See root Justfile for full documentation.
+preview-docs: update-docs-dev-script
+    echo "Requires Python Installed. Version >= 3.11"
+    python --version
+    ./local.py --target "../../docs+local" --exposed-port 8280 cat-voices-docs:latest