doc: display feture flags in docs.rs (#338)

* pass rustdoc-args on docs.rs * use doc_cfg for provenance
tskit-dev · Oct 28, 2022 · fc1142a · fc1142a
1 parent 84c0cb4
commit fc1142a
Show file tree

Hide file tree

Showing 7 changed files with 26 additions and 12 deletions.
diff --git a/Cargo.toml b/Cargo.toml
@@ -50,6 +50,7 @@ derive = ["tskit-derive", "serde", "serde_json", "bincode"]
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "doc_cfg"]
 
 # Not run during tests
 [[example]]

diff --git a/src/_macros.rs b/src/_macros.rs
@@ -1032,7 +1032,8 @@ macro_rules! migration_table_add_row_with_metadata {
     };
 }
 
-#[cfg(any(doc, feature = "provenance"))]
+#[cfg(feature = "provenance")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
 macro_rules! provenance_table_add_row {
     ($(#[$attr:meta])* => $name: ident, $self: ident, $table: expr) => {
         $(#[$attr])*

diff --git a/src/lib.rs b/src/lib.rs
@@ -44,7 +44,7 @@
 //! Some features are optional, and are activated by requesting them in your `Cargo.toml` file.
 //!
 //! * `provenance`
-//!     * Enables [`provenance`]
+//!     * Enables `provenance`
 //! * `derive` enables the following derive macros:
 //!     * [`crate::metadata::MutationMetadata`]
 //!     * [`crate::metadata::IndividualMetadata`]
@@ -72,6 +72,7 @@
 #![allow(non_upper_case_globals)]
 #![allow(non_camel_case_types)]
 #![allow(non_snake_case)]
+#![cfg_attr(doc_cfg, feature(doc_cfg))]
 
 #[allow(deref_nullptr)]
 #[allow(rustdoc::broken_intra_doc_links)]
@@ -444,10 +445,12 @@ pub use tree_interface::{NodeTraversalOrder, TreeInterface};
 pub use trees::{Tree, TreeSequence};
 
 // Optional features
-#[cfg(any(feature = "provenance", doc))]
+#[cfg(feature = "provenance")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
 pub mod provenance;
 
-#[cfg(any(feature = "provenance", doc))]
+#[cfg(feature = "provenance")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
 /// A provenance ID
 ///
 /// This is an integer referring to a row of a [``provenance::ProvenanceTable``].

diff --git a/src/provenance.rs b/src/provenance.rs
@@ -184,7 +184,9 @@ build_owned_table_type!(
     /// # Examples
     ///
     /// ```rust
-    /// # #[cfg(any(doc, feature = "provenance"))] {
+    /// # #[cfg(feature = "provenance")]
+    /// # #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
+    /// {
     /// use tskit::provenance::OwnedProvenanceTable;
     /// let mut provenances = OwnedProvenanceTable::default();
     /// let id = provenances.add_row("message").unwrap();

diff --git a/src/table_collection.rs b/src/table_collection.rs
@@ -848,7 +848,8 @@ impl TableCollection {
         handle_tsk_return_value!(rv)
     }
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     provenance_table_add_row!(
     /// Add provenance record with a time stamp.
     ///
@@ -1159,7 +1160,8 @@ impl TableCollection {
         handle_tsk_return_value!(rv)
     }
 
-    #[cfg(any(doc, feature = "provenance"))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     /// Set the provenance table from an
     /// [`OwnedProvenanceTable`](`crate::provenance::OwnedProvenanceTable`)
     ///
@@ -1231,7 +1233,8 @@ impl TableAccess for TableCollection {
         PopulationTable::new_from_table(&self.inner.populations)
     }
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     fn provenances(&self) -> crate::provenance::ProvenanceTable {
         crate::provenance::ProvenanceTable::new_from_table(&self.inner.provenances)
     }

diff --git a/src/traits.rs b/src/traits.rs
@@ -113,11 +113,13 @@ pub trait TableAccess {
         Box::new(make_table_iterator::<IndividualTable>(self.individuals()))
     }
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     /// Get reference to the [``ProvenanceTable``](crate::provenance::ProvenanceTable)
     fn provenances(&self) -> crate::provenance::ProvenanceTable;
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     /// Return an iterator over provenances
     fn provenances_iter(
         &self,

diff --git a/src/trees.rs b/src/trees.rs
@@ -454,7 +454,8 @@ impl TreeSequence {
         )
     }
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     /// Add provenance record with a time stamp.
     ///
     /// All implementation of this trait provided by `tskit` use
@@ -540,7 +541,8 @@ impl TableAccess for TreeSequence {
         PopulationTable::new_from_table(unsafe { &(*self.inner.tables).populations })
     }
 
-    #[cfg(any(feature = "provenance", doc))]
+    #[cfg(feature = "provenance")]
+    #[cfg_attr(doc_cfg, doc(cfg(feature = "provenance")))]
     fn provenances(&self) -> crate::provenance::ProvenanceTable {
         crate::provenance::ProvenanceTable::new_from_table(unsafe {
             &(*self.inner.tables).provenances