Updated docs to use mdbook

bazelbuild · Sep 5, 2024 · 5d7c990 · 5d7c990
1 parent 13e566e
commit 5d7c990
Show file tree

Hide file tree

Showing 25 changed files with 92 additions and 32 deletions.
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,38 @@
+name: Docs-CI/CD
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types:
+      - opened
+      - synchronize
+
+jobs:
+  docs:
+    name: Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+      - name: Install Rust
+        run: |
+          rustup set profile minimal
+          rustup toolchain install stable
+          rustup default stable
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir bin
+          curl -sSL $url | tar -xz --directory=bin
+          echo "$(pwd)/bin" >> $GITHUB_PATH
+      - name: Run tests
+        run: mdbook build
+        working-directory: docs
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: JamesIves/[email protected]
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: docs/book # The folder the action should deploy.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1 @@
+book
diff --git a/docs/book.toml b/docs/book.toml
@@ -0,0 +1,6 @@
+[book]
+authors = ["UebelAndre"]
+language = "en"
+multilingual = false
+src = "src"
+title = "rules_rust"
diff --git a/docs/main.css b/docs/main.css
diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -0,0 +1,20 @@
+# Summary
+
+[Introduction](./index.md)
+
+---
+
+- [Rules](./rules.md)
+    - [defs](./defs.md)
+    - [rustdoc](./rust_doc.md)
+    - [clippy](./rust_clippy.md)
+    - [rustfmt](./rust_fmt.md)
+    - [proto](./rust_proto.md)
+    - [bindgen](./rust_bindgen.md)
+    - [wasm_bindgen](./rust_wasm_bindgen.md)
+    - [cargo](./cargo.md)
+    - [rust_analyzer](./rust_analyzer.md)
+    - [all symbols](./flatten.md)
+- [External Crates](./external_crates.md)
+    - [crate_universe (bzlmod)](crate_universe_bzlmod.md)
+    - [crate_universe (WORKSPACE)](crate_universe.md)
diff --git a/docs/cargo.md → docs/src/cargo.md b/docs/cargo.md → docs/src/cargo.md
diff --git a/docs/crate_universe.md → docs/src/crate_universe.md b/docs/crate_universe.md → docs/src/crate_universe.md
diff --git a/docs/crate_universe_bzlmod.md → docs/src/crate_universe_bzlmod.md b/docs/crate_universe_bzlmod.md → docs/src/crate_universe_bzlmod.md
diff --git a/docs/defs.md → docs/src/defs.md b/docs/defs.md → docs/src/defs.md
diff --git a/docs/src/external_crates.md b/docs/src/external_crates.md
@@ -0,0 +1,3 @@
+# External Dependencies
+
+[crate_universe](crate_universe.md) ([crate_universe bzlmod](crate_universe_bzlmod.md)) is a tool built into `rules_rust` that can be used to fetch dependencies.
diff --git a/docs/flatten.md → docs/src/flatten.md b/docs/flatten.md → docs/src/flatten.md
diff --git a/docs/index.md → docs/src/index.md b/docs/index.md → docs/src/index.md
@@ -1,4 +1,4 @@
-# [Rules rust](https://github.com/bazelbuild/rules_rust)
+# [Rules Rust](https://github.com/bazelbuild/rules_rust)
 
 ## Overview
 
@@ -51,25 +51,6 @@ rust_register_toolchains()
 
 Don't forget to substitute in your desired release's version number and integrity hash.
 
-## Rules
-
-- [defs](defs.md): standard rust rules for building and testing libraries and binaries.
-- [rust_doc](rust_doc.md): rules for generating and testing rust documentation.
-- [rust_clippy](rust_clippy.md): rules for running [clippy](https://github.com/rust-lang/rust-clippy#readme).
-- [rust_fmt](rust_fmt.md): rules for running [rustfmt](https://github.com/rust-lang/rustfmt#readme).
-- [rust_proto](rust_proto.md): rules for generating [protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io) stubs.
-- [rust_bindgen](rust_bindgen.md): rules for generating C++ bindings.
-- [rust_wasm_bindgen](rust_wasm_bindgen.md): rules for generating [WebAssembly](https://www.rust-lang.org/what/wasm) bindings.
-- [cargo](cargo.md): Rules dedicated to Cargo compatibility. ie: [`build.rs` scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html).
-- [crate_universe (bzlmod)](crate_universe_bzlmod.md): Rules for generating Bazel targets for external crate dependencies when using bzlmod.
-- [crate_universe (WORKSPACE)](crate_universe.md): Rules for generating Bazel targets for external crate dependencies when using WORKSPACE files.
-
-You can also browse the [full API in one page](flatten.md).
-
-### Experimental rules
-
-- [rust_analyzer](rust_analyzer.md): rules for generating `rust-project.json` files for [rust-analyzer](https://rust-analyzer.github.io/)
-
 ## Specifying Rust version
 
 To build with a particular version of the Rust compiler, pass that version to [`rust_register_toolchains`](flatten.md#rust_register_toolchains):
@@ -104,10 +85,6 @@ build --@rules_rust//rust/toolchain/channel=nightly
 
 Failure to do so will result in rules attempting to match a `stable` toolchain when one was not registered.
 
-## External Dependencies
-
-[crate_universe](crate_universe.md) ([crate_universe bzlmod](crate_universe_bzlmod.md)) is a tool built into `rules_rust` that can be used to fetch dependencies.
-
 ## Supported bazel versions
 
 The oldest version of Bazel the `main` branch is tested against is `7.3.1`. Previous versions may still be functional in certain environments, but this is the minimum version we strive to fully support.

diff --git a/docs/providers.md → docs/src/providers.md b/docs/providers.md → docs/src/providers.md
diff --git a/docs/src/rules.md b/docs/src/rules.md
@@ -0,0 +1,18 @@
+# Rules
+
+- [defs](defs.md): standard rust rules for building and testing libraries and binaries.
+- [rust_doc](rust_doc.md): rules for generating and testing rust documentation.
+- [rust_clippy](rust_clippy.md): rules for running [clippy](https://github.com/rust-lang/rust-clippy#readme).
+- [rust_fmt](rust_fmt.md): rules for running [rustfmt](https://github.com/rust-lang/rustfmt#readme).
+- [rust_proto](rust_proto.md): rules for generating [protobuf](https://developers.google.com/protocol-buffers) and [gRPC](https://grpc.io) stubs.
+- [rust_bindgen](rust_bindgen.md): rules for generating C++ bindings.
+- [rust_wasm_bindgen](rust_wasm_bindgen.md): rules for generating [WebAssembly](https://www.rust-lang.org/what/wasm) bindings.
+- [cargo](cargo.md): Rules dedicated to Cargo compatibility. ie: [`build.rs` scripts](https://doc.rust-lang.org/cargo/reference/build-scripts.html).
+- [crate_universe (bzlmod)](crate_universe_bzlmod.md): Rules for generating Bazel targets for external crate dependencies when using bzlmod.
+- [crate_universe (WORKSPACE)](crate_universe.md): Rules for generating Bazel targets for external crate dependencies when using WORKSPACE files.
+
+You can also browse the [full API in one page](flatten.md).
+
+## Experimental rules
+
+- [rust_analyzer](rust_analyzer.md): rules for generating `rust-project.json` files for [rust-analyzer](https://rust-analyzer.github.io/)
diff --git a/docs/rust_analyzer.md → docs/src/rust_analyzer.md b/docs/rust_analyzer.md → docs/src/rust_analyzer.md
diff --git a/docs/rust_bindgen.md → docs/src/rust_bindgen.md b/docs/rust_bindgen.md → docs/src/rust_bindgen.md
diff --git a/docs/rust_clippy.md → docs/src/rust_clippy.md b/docs/rust_clippy.md → docs/src/rust_clippy.md
diff --git a/docs/rust_doc.md → docs/src/rust_doc.md b/docs/rust_doc.md → docs/src/rust_doc.md
diff --git a/docs/rust_fmt.md → docs/src/rust_fmt.md b/docs/rust_fmt.md → docs/src/rust_fmt.md
diff --git a/docs/rust_proto.md → docs/src/rust_proto.md b/docs/rust_proto.md → docs/src/rust_proto.md
diff --git a/docs/rust_repositories.md → docs/src/rust_repositories.md b/docs/rust_repositories.md → docs/src/rust_repositories.md
diff --git a/docs/rust_wasm_bindgen.md → docs/src/rust_wasm_bindgen.md b/docs/rust_wasm_bindgen.md → docs/src/rust_wasm_bindgen.md
diff --git a/docs/settings.md → docs/src/settings.md b/docs/settings.md → docs/src/settings.md
diff --git a/docs/test_docs.sh b/docs/test_docs.sh
@@ -15,8 +15,8 @@ pushd "${DOCS_WORKSPACE}" &> /dev/null
 # docs artifacts in the new commit.
 bazel clean \
 && bazel build //... \
-&& cp bazel-bin/*.md . \
-&& chmod 0644 *.md
+&& cp bazel-bin/*.md ./src/ \
+&& chmod 0644 ./src/*.md
 
 if [ -n "$(git status --porcelain)" ]; then 
     >&2 git status

diff --git a/docs/update_docs.sh b/docs/update_docs.sh
@@ -14,11 +14,11 @@ pushd "${DOCS_WORKSPACE}" &> /dev/null
 # docs artifacts in the new commit.
 bazel clean \
 && bazel build //... \
-&& cp bazel-bin/*.md . \
-&& chmod 0644 *.md
+&& cp bazel-bin/*.md ./src/ \
+&& chmod 0644 ./src/*.md
 
 if [[ -z "${SKIP_COMMIT:-}" ]]; then
-    git add *.md && git commit -m "Regenerate documentation"
+    git add src/*.md && git commit -m "Regenerate documentation"
 fi
 
 popd &> /dev/null