add doc build check (#180)

.github/workflows/build.yml

@@ -59,4 +59,20 @@ jobs:
       - run: python3 build.py test --features "${{ matrix.features }}"
         if: ${{ matrix.no-test != true }}
       - run: python3 build.py lint --features "${{ matrix.features }}" ${{ matrix.no-example && '--no-example' }}
-        if: ${{ matrix.lint == true }}
+        if: ${{ matrix.lint == true }}
+
+
+  build-docs:
+    name: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: ./.github/actions/setup-build
+        with:
+          os: ubuntu-latest
+          toolchain: nightly
+      - run: python3 build.py doc
+      - uses: dtolnay/install@cargo-docs-rs
+      - run: cargo docs-rs

.github/workflows/pr.yml

@@ -125,10 +125,28 @@ jobs:
       - run: |
           python3 build.py test --miri
 
+  build-docs:
+    needs: changed-files
+    if: ${{ needs.changed-files.outputs.src == 'true' }}
+    name: build-docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true
+      - uses: ./.github/actions/setup-build
+        with:
+          os: ubuntu-latest
+          toolchain: nightly
+      - run: python3 build.py doc
+      - uses: dtolnay/install@cargo-docs-rs
+      - run: cargo docs-rs
+
   auto-merge:
     needs:
       - all-tests-passed
       - miri
+      - build-docs
     permissions:
       pull-requests: write
       contents: write

autd3-driver/src/datagram/silencer.rs

@@ -103,6 +103,10 @@ impl Silencer<FixedCompletionTime> {
     /// Whether the strict mode is enabled. The default is `true`.
     ///
     /// If the strict mode is enabled, an error is returned if the phase/intensity change of [`Modulation`], [`FociSTM`] or [`GainSTM`] cannot be completed within the time specified by the silencer.
+    ///
+    /// [`Modulation`]: crate::datagram::Modulation
+    /// [`FociSTM`]: crate::datagram::FociSTM
+    /// [`GainSTM`]: crate::datagram::GainSTM
     pub const fn strict_mode(&self) -> bool {
         self.strict_mode
     }

autd3-driver/src/firmware/fpga/mod.rs

@@ -34,6 +34,8 @@ use crate::{
 pub const FPGA_MAIN_CLK_FREQ: Freq<u32> = Freq { freq: 10240000 };
 
 /// The unit of the fixed-point number used in the [`FociSTM`].
+///
+/// [`FociSTM`]: crate::datagram::FociSTM
 pub const FOCI_STM_FIXED_NUM_UNIT: f32 = 0.025 * mm;
 const FOCI_STM_FIXED_NUM_WIDTH: usize = 18;
 const FOCI_STM_FIXED_NUM_UPPER: i32 = (1 << (FOCI_STM_FIXED_NUM_WIDTH - 1)) - 1;

autd3-driver/src/firmware/operation/segment.rs

@@ -15,6 +15,8 @@ use derive_new::new;
 use zerocopy::{Immutable, IntoBytes};
 
 /// [`Datagram`] to change the segment.
+///
+/// [`Datagram`]: crate::datagram::Datagram
 #[derive(Debug, Clone, Copy)]
 pub enum SwapSegment {
     /// Change the [`Gain`] segment.

autd3-driver/src/lib.rs

@@ -30,7 +30,10 @@ pub mod utils;
 #[cfg(feature = "async-trait")]
 pub use async_trait::async_trait;
 
-/// Utilities for user-defined [`Gain`] and `Modulation`.
+/// Utilities for user-defined [`Gain`] and [`Modulation`].
+///
+/// [`Gain`]: crate::datagram::Gain
+/// [`Modulation`]: crate::datagram::Modulation
 #[cfg(feature = "derive")]
 pub mod derive {
     pub use crate::{

autd3-link-twincat/Cargo.toml

@@ -26,3 +26,7 @@ remote = ["itertools", "cc", "tracing"]
 default = ["local"]
 all = ["local", "remote"]
 async-trait = ["autd3-driver/async-trait"]
+
+[package.metadata.docs.rs]
+all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

autd3-link-twincat/src/lib.rs

@@ -1,12 +1,16 @@
+#![cfg_attr(docsrs, feature(doc_cfg))]
+
 mod error;
 
 #[cfg(feature = "local")]
 pub mod local;
+#[cfg_attr(docsrs, doc(cfg(feature = "remote")))]
 #[cfg(feature = "remote")]
 pub mod remote;
 
 #[cfg(feature = "local")]
 pub use local::TwinCAT;
 
+#[cfg_attr(docsrs, doc(cfg(feature = "remote")))]
 #[cfg(feature = "remote")]
 pub use remote::RemoteTwinCAT;

build.py

@@ -95,6 +95,11 @@ def rust_lint(args) -> None:  # noqa: ANN001
     run_command(command)
 
 
+def rust_doc(_) -> None:  # noqa: ANN001
+    with with_env(RUSTDOCFLAGS="--cfg docsrs -D warnings"):
+        run_command(["cargo", "+nightly", "doc", "--workspace", "--no-deps"])
+
+
 def rust_test(args) -> None:  # noqa: ANN001
     config = Config(args)
     if args.miri:
@@ -278,6 +283,10 @@ def command_help(args) -> None:  # noqa: ANN001
         parser_lint.add_argument("--no-examples", action="store_true", help="skip examples")
         parser_lint.set_defaults(handler=rust_lint)
 
+        # doc
+        parser_doc = subparsers.add_parser("doc", help="see `doc -h`")
+        parser_doc.set_defaults(handler=rust_doc)
+
         # test
         parser_test = subparsers.add_parser("test", help="see `test -h`")
         parser_test.add_argument("--release", action="store_true", help="release build")