From e97988273b809b6fb5e435478469cd19ab76526c Mon Sep 17 00:00:00 2001 From: UebelAndre Date: Thu, 5 Sep 2024 10:51:48 -0700 Subject: [PATCH] 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 | 38 +++++++++++++++++++++++++ docs/.gitignore | 1 + docs/book.toml | 6 ++++ docs/main.css | 3 -- docs/src/SUMMARY.md | 20 +++++++++++++ docs/{ => src}/cargo.md | 0 docs/{ => src}/crate_universe.md | 0 docs/{ => src}/crate_universe_bzlmod.md | 0 docs/{ => src}/defs.md | 0 docs/src/external_crates.md | 3 ++ docs/{ => src}/flatten.md | 0 docs/{ => src}/index.md | 25 +--------------- docs/{ => src}/providers.md | 0 docs/src/rules.md | 18 ++++++++++++ docs/{ => src}/rust_analyzer.md | 0 docs/{ => src}/rust_bindgen.md | 0 docs/{ => src}/rust_clippy.md | 0 docs/{ => src}/rust_doc.md | 0 docs/{ => src}/rust_fmt.md | 0 docs/{ => src}/rust_proto.md | 0 docs/{ => src}/rust_repositories.md | 0 docs/{ => src}/rust_wasm_bindgen.md | 0 docs/{ => src}/settings.md | 0 docs/test_docs.sh | 4 +-- docs/update_docs.sh | 6 ++-- 25 files changed, 92 insertions(+), 32 deletions(-) create mode 100644 .github/workflows/docs.yaml create mode 100644 docs/.gitignore create mode 100644 docs/book.toml delete mode 100755 docs/main.css create mode 100644 docs/src/SUMMARY.md rename docs/{ => src}/cargo.md (100%) rename docs/{ => src}/crate_universe.md (100%) rename docs/{ => src}/crate_universe_bzlmod.md (100%) rename docs/{ => src}/defs.md (100%) create mode 100644 docs/src/external_crates.md rename docs/{ => src}/flatten.md (100%) rename docs/{ => src}/index.md (69%) rename docs/{ => src}/providers.md (100%) create mode 100644 docs/src/rules.md rename docs/{ => src}/rust_analyzer.md (100%) rename docs/{ => src}/rust_bindgen.md (100%) rename docs/{ => src}/rust_clippy.md (100%) rename docs/{ => src}/rust_doc.md (100%) rename docs/{ => src}/rust_fmt.md (100%) rename docs/{ => src}/rust_proto.md (100%) rename docs/{ => src}/rust_repositories.md (100%) rename docs/{ => src}/rust_wasm_bindgen.md (100%) rename docs/{ => src}/settings.md (100%) diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 0000000000..ed88e37c5d --- /dev/null +++ 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/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. diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000000..7585238efe --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000000..f8efa70ad7 --- /dev/null +++ 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 deleted file mode 100755 index f506e12273..0000000000 --- a/docs/main.css +++ /dev/null @@ -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 */ \ No newline at end of file diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000000..522336212e --- /dev/null +++ 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 b/docs/src/cargo.md similarity index 100% rename from docs/cargo.md rename to docs/src/cargo.md diff --git a/docs/crate_universe.md b/docs/src/crate_universe.md similarity index 100% rename from docs/crate_universe.md rename to docs/src/crate_universe.md diff --git a/docs/crate_universe_bzlmod.md b/docs/src/crate_universe_bzlmod.md similarity index 100% rename from docs/crate_universe_bzlmod.md rename to docs/src/crate_universe_bzlmod.md diff --git a/docs/defs.md b/docs/src/defs.md similarity index 100% rename from docs/defs.md rename to docs/src/defs.md diff --git a/docs/src/external_crates.md b/docs/src/external_crates.md new file mode 100644 index 0000000000..903fd14638 --- /dev/null +++ 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 b/docs/src/flatten.md similarity index 100% rename from docs/flatten.md rename to docs/src/flatten.md diff --git a/docs/index.md b/docs/src/index.md similarity index 69% rename from docs/index.md rename to docs/src/index.md index 83df744834..cf4d4184d7 100644 --- a/docs/index.md +++ b/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 b/docs/src/providers.md similarity index 100% rename from docs/providers.md rename to docs/src/providers.md diff --git a/docs/src/rules.md b/docs/src/rules.md new file mode 100644 index 0000000000..52a1f7f3fd --- /dev/null +++ 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 b/docs/src/rust_analyzer.md similarity index 100% rename from docs/rust_analyzer.md rename to docs/src/rust_analyzer.md diff --git a/docs/rust_bindgen.md b/docs/src/rust_bindgen.md similarity index 100% rename from docs/rust_bindgen.md rename to docs/src/rust_bindgen.md diff --git a/docs/rust_clippy.md b/docs/src/rust_clippy.md similarity index 100% rename from docs/rust_clippy.md rename to docs/src/rust_clippy.md diff --git a/docs/rust_doc.md b/docs/src/rust_doc.md similarity index 100% rename from docs/rust_doc.md rename to docs/src/rust_doc.md diff --git a/docs/rust_fmt.md b/docs/src/rust_fmt.md similarity index 100% rename from docs/rust_fmt.md rename to docs/src/rust_fmt.md diff --git a/docs/rust_proto.md b/docs/src/rust_proto.md similarity index 100% rename from docs/rust_proto.md rename to docs/src/rust_proto.md diff --git a/docs/rust_repositories.md b/docs/src/rust_repositories.md similarity index 100% rename from docs/rust_repositories.md rename to docs/src/rust_repositories.md diff --git a/docs/rust_wasm_bindgen.md b/docs/src/rust_wasm_bindgen.md similarity index 100% rename from docs/rust_wasm_bindgen.md rename to docs/src/rust_wasm_bindgen.md diff --git a/docs/settings.md b/docs/src/settings.md similarity index 100% rename from docs/settings.md rename to docs/src/settings.md diff --git a/docs/test_docs.sh b/docs/test_docs.sh index 3e51ad7b5e..98c2a0c8e4 100755 --- 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 index edadbfab35..be6cfabf27 100755 --- 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