Updated docs to use mdbook (#2834)

This updates docs to be built using
[mdbook](https://rust-lang.github.io/mdBook/) for improved readability
and search-ability. Note that the raw markdown from stardoc is still
committed to the repo and can be easily viewed at any commit to ensure
users are able to get the correct docs for their current version of
rules_rust.

.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/github-pages-deploy-action@4.1.7
+        with:
+          branch: gh-pages # The branch the action should deploy to.
+          folder: docs/book # The folder the action should deploy.

docs/.gitignore

@@ -0,0 +1 @@
+book

docs/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["UebelAndre"]
+language = "en"
+multilingual = false
+src = "src"
+title = "rules_rust"

docs/main.css

@@ -1,3 +0,0 @@
-body{background-color:#fafafa}pre,code{font-family:'Liberation Mono', Consolas, Monaco, 'Andale Mono', monospace}pre{background-color:#eee;padding:20px;overflow-x:auto;word-wrap:normal}pre code{overflow-wrap:normal;white-space:pre}code{display:inline-block;font-size:90%;white-space:pre-wrap}.mdl-layout__drawer{background-color:#fff}.mdl-layout__drawer .mdl-layout-title{border-bottom:1px solid #e0e0e0;padding-left:24px}.drawer-nav ul{list-style:none;padding-left:0}.drawer-nav ul li{display:block;padding:0}.drawer-nav ul li ul li a{padding-left:44px;font-weight:400}.drawer-nav ul li a{display:block;flex-shrink:0;padding:15px 0 15px 22px;margin:0;font-weight:600;color:#757575;line-height:1em;text-decoration:none;cursor:pointer}.drawer-nav ul li a:active,.drawer-nav ul li a:hover{background-color:#f0f0f0}.drawer-nav ul li.active a{color:#4caf50;font-weight:500}h1.page-title{font-size:34px;font-weight:400;line-height:40px;margin-bottom:30px;color:#4caf50}p.lead{font-size:20px;line-height:32px}table{border-collapse:collapse;border-spacing:0;background-color:#fff;table-layout:auto}table thead th{background-color:#fafafa;border:1px solid #eee;color:#757575;padding:12px 12px 12px 24px;vertical-align:top}table tbody td{border:1px solid #eee;padding:12px 12px 12px 24px;vertical-align:top}table.params-table{width:100%}table.params-table col.col-param{width:25%}table.params-table col.col-description{width:75%}table.overview-table{width:100%}table.overview-table col.col-name{width:25%}table.overview-table col.col-description{width:75%}table.overview-table td p{margin:0}hr{margin-top:80px;margin-bottom:80px}nav.toc{border-left:5px solid #4caf50;padding-left:20px;margin-bottom:48px}nav.toc h1,nav.toc h2{font-size:15px;line-height:16px;padding-bottom:12px;margin-bottom:0;font-weight:400;color:#757575}nav.toc ul{list-style:none;margin-top:0;padding-left:0}nav.toc ul li{font-size:20px;line-height:40px}nav.toc ul li a{color:#4caf50}.page-content{margin-left:auto;margin-right:auto;padding-top:60px;padding-bottom:60px;width:760px}.page-content a{text-decoration:none}.page-content h1{font-size:34px;font-weight:400;line-height:40px;margin-bottom:30px;color:#4caf50}.page-content h2{font-size:24px;font-weight:400;line-height:32px;margin-bottom:30px;color:#4caf50}.page-content h3{font-size:20px;font-weight:400;line-height:32px;margin-bottom:30px;color:#4caf50}@media (max-width: 768px){.page-content{width:360px}}@media (min-width: 768px){.page-content{width:760px}}@media (min-width: 1476px){.page-content{width:1160px}}.mdl-mini-footer{padding-left:40px}
-
-/*# sourceMappingURL=main.css.map */

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)

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.

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.

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/)

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

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