feat(docs): Integrate Rust docs to our general mkDocs (#173)

* Add rust docs deployment * fix * fix * update * embed Rust docs * add dependency graphs * update * fix * update * fix * fix * update Earthly versions * fix Rust build
input-output-hk · Dec 12, 2023 · 301d953 · 301d953
1 parent f164369
commit 301d953
Show file tree

Hide file tree

Showing 12 changed files with 74 additions and 23 deletions.
diff --git a/catalyst-gateway/.cargo/config.toml b/catalyst-gateway/.cargo/config.toml
@@ -49,6 +49,9 @@ rustflags = [
 ]
 
 rustdocflags = [
+    "--enable-index-page",
+    "-Z",
+    "unstable-options",
     "-D",
     "warnings",
     "-D",
@@ -104,7 +107,6 @@ lto = "thin"
 incremental = false
 codegen-units = 16
 
-
 [alias]
 lint = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable -D clippy::missing_docs_in_private_items"
 lintfix = "clippy -- -D warnings -D clippy::pedantic -D clippy::unwrap_used -D clippy::expect_used -D clippy::exit -D clippy::get_unwrap -D clippy::index_refutable_slice -D clippy::indexing_slicing -D clippy::match_on_vec_items -D clippy::match_wild_err_arm -D clippy::missing_panics_doc -D clippy::panic -D clippy::string_slice -D clippy::unchecked_duration_subtraction -D clippy::unreachable"

diff --git a/catalyst-gateway/Earthfile b/catalyst-gateway/Earthfile
@@ -4,17 +4,17 @@ VERSION 0.7
 
 # Set up our target toolchains, and copy our files.
 builder:
-    FROM github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.3+rust-base
+    FROM github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.11+rust-base
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.3+SETUP --toolchain=rust-toolchain.toml
+    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.11+SETUP --toolchain=rust-toolchain.toml
 
     COPY --dir .cargo .config Cargo.* clippy.toml deny.toml rustfmt.toml bin crates .
 
 # Test rust build container - Use best architecture host tools.
 check-hosted:
     FROM +builder
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.3+CHECK
+    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.11+CHECK
 
 # Test which runs check with all supported host tooling.  Needs qemu or rosetta to run.
 # Only used to validate tooling is working across host toolsets.
@@ -27,9 +27,9 @@ build-hosted:
     # Build the service
     FROM +builder
 
-    RUN /scripts/std_build.sh
+    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.11+BUILD --bins="cat-gateway/cat-gateway"
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.3+SMOKE_TEST --bin=cat-gateway
+    DO github.com/input-output-hk/catalyst-ci/earthly/rust:v2.0.11+SMOKE_TEST --bin="cat-gateway"
 
     SAVE ARTIFACT target/$TARGETARCH/doc doc
     SAVE ARTIFACT target/$TARGETARCH/release/cat-gateway cat-gateway
@@ -39,6 +39,7 @@ build-hosted:
 build-all-hosts:    
     BUILD --platform=linux/amd64 --platform=linux/arm64 +build-hosted
 
+
 ## -----------------------------------------------------------------------------
 ##
 ## Standard CI targets.

diff --git a/catalyst-gateway/bin/Cargo.toml b/catalyst-gateway/bin/Cargo.toml
@@ -9,14 +9,6 @@ edition.workspace = true
 license.workspace = true
 repository.workspace = true
 
-[[bin]]
-name = "cat-gateway"
-path = "src/main.rs"
-
-[lib]
-name = "lib"
-path = "src/lib.rs"
-
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]

diff --git a/catalyst-gateway/clippy.toml b/catalyst-gateway/clippy.toml
@@ -1 +1 @@
-allow-unwrap-in-tests = true
+allow-expect-in-tests = true
diff --git a/docs/Earthfile b/docs/Earthfile
@@ -6,21 +6,23 @@ VERSION 0.7
 # Copy all the source we need to build the docs
 src:
     # Common src setup
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+SRC
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+SRC
 
     # Now copy into that any artifacts we pull from the builds.
     COPY --dir ../+repo-docs/repo /docs/includes
+    # copy Rust docs
+    COPY ./../catalyst-gateway+build-hosted/doc /docs/src/api/catalyst-gateway/rust-docs
 
 # Build the docs here.
 docs:
     FROM +src
 
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+BUILD
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+BUILD
 
 # Make a locally runable container that can serve the docs.
 local:
     # Build a self contained service to show built docs locally.
-    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.8+PACKAGE
+    DO github.com/input-output-hk/catalyst-ci/earthly/docs:v2.0.11+PACKAGE
 
     # Copy the static pages into the container
     COPY +docs/ /usr/share/nginx/html

diff --git a/docs/src/.pages b/docs/src/.pages
@@ -1,6 +1,7 @@
-arrange:
-  - index.md
+nav:
+  - 'Home': index.md
   - getting-started
   - catalyst-standards
+  - 'API': api
   - architecture
   - appendix
diff --git a/docs/src/api/.pages b/docs/src/api/.pages
@@ -0,0 +1,3 @@
+nav:
+  - index.md
+  - 'Catalyst gateway': catalyst-gateway.md
diff --git a/docs/src/api/catalyst-gateway.md b/docs/src/api/catalyst-gateway.md
@@ -0,0 +1,46 @@
+---
+icon: material/gate
+---
+
+<!-- cspell: words RUSTDOC graphviz -->
+
+# Catalyst Gateway Rust docs
+
+<!-- markdownlint-disable no-inline-html -->
+<iframe src="rust-docs/index.html" title="RUSTDOC Documentation" style="height:800px;width:100%;"></iframe>
+
+[OPEN FULL PAGE](./catalyst-gateway/rust-docs/index.html)
+
+## Workspace Dependency Graph
+
+```kroki-graphviz
+@from_file:./api/catalyst-gateway/rust-docs/workspace.dot
+```
+
+## External Dependencies Graph
+
+```kroki-graphviz
+@from_file:./api/catalyst-gateway/rust-docs/full.dot
+```
+
+## Build and Development Dependencies Graph
+
+```kroki-graphviz
+@from_file:./api/catalyst-gateway/rust-docs/all.dot
+```
+
+## Module trees
+
+### cat-gateway crate
+
+```rust
+    {{ include_file('src/api/catalyst-gateway/rust-docs/cat-gateway.cat-gateway.bin.modules.tree') }}
+```
+
+## Module graphs
+
+### cat-gateway crate
+
+```kroki-graphviz
+@from_file:./api/catalyst-gateway/rust-docs/cat-gateway.cat-gateway.bin.modules.dot
+```
diff --git a/docs/src/api/index.md b/docs/src/api/index.md
@@ -0,0 +1,5 @@
+---
+icon: material/api
+---
+
+# Catalyst Voices API docs
diff --git a/docs/src/appendix/important/.pages b/docs/src/appendix/important/.pages
@@ -1,4 +1,4 @@
-arrange:
+nav:
   - index.md
   - contributing.md
   - coc.md

diff --git a/docs/src/architecture/.pages b/docs/src/architecture/.pages
@@ -1,4 +1,4 @@
-arrange:
+nav:
   - index.md
   - 01_introduction_and_goals.md
   - 02_architecture_constraints.md

diff --git a/docs/src/catalyst-standards/index.md b/docs/src/catalyst-standards/index.md
@@ -2,7 +2,6 @@
 icon: material/pillar
 ---
 
-<!-- markdownlint-disable MD025-->
 # Catalyst Standards
 
 These are documents that relate to standardized specifications of the catalyst stack.
Original file line number	Diff line number	Diff line change
		@@ -1 +1 @@
		allow-unwrap-in-tests = true
		allow-expect-in-tests = true