bazelbuild · UebelAndre · Sep 5, 2024 · Sep 5, 2024
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:/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:/bazelbuild/rules_rust)
+# [Rules Rust](https:/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:/rust-lang/rust-clippy#readme).
-- [rust_fmt](rust_fmt.md): rules for running [rustfmt](https:/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:/rust-lang/rust-clippy#readme).
+- [rust_fmt](rust_fmt.md): rules for running [rustfmt](https:/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