docs: Enable doc_auto_cfg when docs cfg has been enabled (#3835)

* docs: Enable doc_auto_cfg when docs cfg has been enabled Signed-off-by: Xuanwo <[email protected]> * Fix typo Signed-off-by: Xuanwo <[email protected]> * Address links Signed-off-by: Xuanwo <[email protected]> --------- Signed-off-by: Xuanwo <[email protected]>
apache · Dec 27, 2023 · 6ca583d · 6ca583d
1 parent a9e0a03
commit 6ca583d
Show file tree

Hide file tree

Showing 7 changed files with 15 additions and 13 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -47,15 +47,21 @@ jobs:
           need-protoc: true
           github-token: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Setup Rust Nightly
+        run: |
+          rustup toolchain install nightly
+
       - uses: actions/setup-java@v4
         with:
           distribution: temurin
           java-version: '17'
 
       - name: Build OpenDAL doc
-        run: cargo doc --lib --no-deps --all-features -p opendal
+        run: cargo +nightly doc --lib --no-deps --all-features -p opendal
         env:
           LD_LIBRARY_PATH: ${{ env.JAVA_HOME }}/lib/server:${{ env.LD_LIBRARY_PATH }}
+          # Enable cfg docs to make sure docs are built.
+          RUSTDOCFLAGS: "--cfg docs"
 
       - name: Upload docs
         uses: actions/upload-artifact@v3

diff --git a/core/Cargo.toml b/core/Cargo.toml
@@ -32,6 +32,7 @@ version.workspace = true
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docs"]
 
 [features]
 default = [
@@ -53,12 +54,6 @@ default = [
   "services-azfile",
 ]
 
-# Build docs or not.
-#
-# This features is used to control whether or not to build opendal's docs.
-# And doesn't have any other effects.
-docs = []
-
 # Build test utils or not.
 #
 # This features is used to control whether or not to build opendal's test utils.

diff --git a/core/src/docs/features.md b/core/src/docs/features.md
@@ -16,7 +16,6 @@
 - `services-moka`: Enable moka service support.
 - `services-ipfs`: Enable ipfs service support.
 - `services-redis`: Enable redis service support without TLS.
-- `services-redis-rustls`: Enable redis service support with `rustls`.
 - `services-redis-native-tls`: Enable redis service support with `native-tls`.
 - `services-rocksdb`: Enable rocksdb service support.
 - `services-atomicserver`: Enable atomicserver service support.

diff --git a/core/src/lib.rs b/core/src/lib.rs
@@ -15,6 +15,8 @@
 // specific language governing permissions and limitations
 // under the License.
 
+#![cfg_attr(docs, feature(doc_auto_cfg))]
+
 //! OpenDAL is the Open Data Access Layer to **freely** access data.
 //!
 //! - Documentation: All docs are carried by self, visit [`docs`] for more.
@@ -70,7 +72,7 @@ mod types;
 pub use types::*;
 
 // Public modules, they will be accessed like `opendal::layers::Xxxx`
-#[cfg(feature = "docs")]
+#[cfg(docs)]
 pub mod docs;
 pub mod layers;
 pub mod raw;

diff --git a/core/src/services/azfile/backend.rs b/core/src/services/azfile/backend.rs
@@ -118,7 +118,7 @@ impl AzfileBuilder {
     /// Set file share name of this backend.
     ///
     /// # Notes
-    /// You can find more about from: https://learn.microsoft.com/en-us/rest/api/storageservices/operations-on-shares--file-service
+    /// You can find more about from: <https://learn.microsoft.com/en-us/rest/api/storageservices/operations-on-shares--file-service>
     pub fn share_name(&mut self, share_name: &str) -> &mut Self {
         if !share_name.is_empty() {
             self.share_name = share_name.to_string();

diff --git a/core/src/services/b2/backend.rs b/core/src/services/b2/backend.rs
@@ -136,15 +136,15 @@ impl B2Builder {
     }
 
     /// Set bucket name of this backend.
-    /// You can find it in https://secure.backblaze.com/b2_buckets.html
+    /// You can find it in <https://secure.backblaze.com/b2_buckets.html>
     pub fn bucket(&mut self, bucket: &str) -> &mut Self {
         self.config.bucket = bucket.to_string();
 
         self
     }
 
     /// Set bucket id of this backend.
-    /// You can find it in https://secure.backblaze.com/b2_buckets.html
+    /// You can find it in <https://secure.backblaze.com/b2_buckets.html>
     pub fn bucket_id(&mut self, bucket_id: &str) -> &mut Self {
         self.config.bucket_id = bucket_id.to_string();
 

diff --git a/core/src/services/sftp/error.rs b/core/src/services/sftp/error.rs
@@ -45,7 +45,7 @@ impl From<SftpClientError> for Error {
     }
 }
 
-/// REMOVE ME: it's not allowed to impl <T> for Error.
+/// REMOVE ME: it's not allowed to impl `<T>` for Error.
 impl From<SshError> for Error {
     fn from(e: SshError) -> Self {
         Error::new(ErrorKind::Unexpected, "ssh error").set_source(e)