From 301d953e06786831ca97ac9cf0fdc64248cfbc5a Mon Sep 17 00:00:00 2001 From: Alex Pozhylenkov Date: Tue, 12 Dec 2023 11:40:16 +0200 Subject: [PATCH] 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 --- catalyst-gateway/.cargo/config.toml | 4 ++- catalyst-gateway/Earthfile | 11 ++++--- catalyst-gateway/bin/Cargo.toml | 8 ----- catalyst-gateway/clippy.toml | 2 +- docs/Earthfile | 8 +++-- docs/src/.pages | 5 +-- docs/src/api/.pages | 3 ++ docs/src/api/catalyst-gateway.md | 46 ++++++++++++++++++++++++++++ docs/src/api/index.md | 5 +++ docs/src/appendix/important/.pages | 2 +- docs/src/architecture/.pages | 2 +- docs/src/catalyst-standards/index.md | 1 - 12 files changed, 74 insertions(+), 23 deletions(-) create mode 100644 docs/src/api/.pages create mode 100644 docs/src/api/catalyst-gateway.md create mode 100644 docs/src/api/index.md diff --git a/catalyst-gateway/.cargo/config.toml b/catalyst-gateway/.cargo/config.toml index e8463c6a508..0dd1a3104ea 100644 --- 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 index c2d967d0271..f41c71776dd 100644 --- a/catalyst-gateway/Earthfile +++ b/catalyst-gateway/Earthfile @@ -4,9 +4,9 @@ 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 . @@ -14,7 +14,7 @@ builder: 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 index 1f2aa80104b..7eed5d26d75 100644 --- 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 index 154626ef4e8..6933b816419 100644 --- 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 index 5d8c5694f73..ce302f5fef9 100644 --- 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 index 14d3d96d7c8..61586bcb927 100644 --- 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 new file mode 100644 index 00000000000..a6bb24b5d98 --- /dev/null +++ b/docs/src/api/.pages @@ -0,0 +1,3 @@ +nav: + - index.md + - 'Catalyst gateway': catalyst-gateway.md \ No newline at end of file diff --git a/docs/src/api/catalyst-gateway.md b/docs/src/api/catalyst-gateway.md new file mode 100644 index 00000000000..e79572beb97 --- /dev/null +++ b/docs/src/api/catalyst-gateway.md @@ -0,0 +1,46 @@ +--- +icon: material/gate +--- + + + +# Catalyst Gateway Rust docs + + + + +[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 new file mode 100644 index 00000000000..17fd0dbb854 --- /dev/null +++ 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 index 2386aeb6a21..eb43dc2f82e 100644 --- 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 index 6422cc2c62f..870e4627de2 100644 --- 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 index 3e1970666cf..14cc06e7991 100644 --- a/docs/src/catalyst-standards/index.md +++ b/docs/src/catalyst-standards/index.md @@ -2,7 +2,6 @@ icon: material/pillar --- - # Catalyst Standards These are documents that relate to standardized specifications of the catalyst stack.