From 6a7a65d9296f4f5fdfa32ce4ee7e9c9e684b4f67 Mon Sep 17 00:00:00 2001 From: Emi Tatsuo Date: Fri, 11 Dec 2020 14:28:30 -0500 Subject: [PATCH] Added unstable doc attributes to generate fancy docs --- Cargo.toml | 3 +++ src/cert.rs | 2 ++ src/handling.rs | 2 ++ src/lib.rs | 10 ++++++++++ src/types/body.rs | 2 ++ src/types/request.rs | 3 +++ src/user_management/mod.rs | 5 +++++ src/user_management/user.rs | 4 ++++ src/util.rs | 3 +++ 9 files changed, 34 insertions(+) diff --git a/Cargo.toml b/Cargo.toml index ab08f34..f883be4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -58,3 +58,6 @@ required-features = ["serve_dir"] [[example]] name = "ratelimiting" required-features = ["ratelimiting"] + +[package.metadata.docs.rs] +rustc-args = ["--cfg", "docsrs"] diff --git a/src/cert.rs b/src/cert.rs index b027e92..85b773e 100644 --- a/src/cert.rs +++ b/src/cert.rs @@ -26,6 +26,7 @@ use rustls::*; #[derive(Clone, Debug)] #[cfg(feature = "certgen")] +#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))] /// The mode to use for determining the domains to use for a new certificate. /// /// Used to configure a [`Server`] using [`set_certificate_generation_mode()`] @@ -45,6 +46,7 @@ pub enum CertGenMode { } #[cfg(feature = "certgen")] +#[cfg_attr(docsrs, doc(cfg(feature = "certgen")))] impl CertGenMode { /// Generate a new self-signed certificate /// diff --git a/src/handling.rs b/src/handling.rs index ba72283..54d0477 100644 --- a/src/handling.rs +++ b/src/handling.rs @@ -56,6 +56,7 @@ pub enum Handler { StaticHandler(Response), #[cfg(feature = "serve_dir")] + #[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))] /// A handler that serves a directory, including a directory listing /// /// Most often created with [`From`] @@ -208,6 +209,7 @@ impl From<&Document> for Handler { } #[cfg(feature = "serve_dir")] +#[doc(cfg(feature = "serve_dir"))] impl From for Handler { /// Serve files from a directory /// diff --git a/src/lib.rs b/src/lib.rs index 142e61d..9adc12e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -237,6 +237,7 @@ pub mod routing; #[cfg(feature = "ratelimiting")] mod ratelimiting; #[cfg(feature = "user_management")] +#[doc(cfg(feature = "user_management"))] pub mod user_management; #[cfg(feature = "gemini_srv")] mod cert; @@ -244,6 +245,7 @@ mod cert; #[cfg(feature="user_management")] use user_management::UserManager; #[cfg(feature = "certgen")] +#[doc(cfg(feature = "certgen"))] pub use cert::CertGenMode; pub use uriparse::URIReference; @@ -708,6 +710,7 @@ impl Server { } #[cfg(feature="user_management")] + #[doc(cfg(feature = "user_management"))] /// Sets the directory to store user data in /// /// This will only be used if a database is not provided with [`set_database()`]. @@ -721,6 +724,7 @@ impl Server { } #[cfg(feature="user_management")] + #[doc(cfg(feature = "user_management"))] /// Sets a specific database to use /// /// This opens to trees within the database, both namespaced to avoid collisions. @@ -735,6 +739,7 @@ impl Server { } #[cfg(feature="certgen")] + #[doc(cfg(feature = "certgen"))] /// Determine where certificate config comes from, if generation is required /// /// If a certificate & keyfile are not available on the provided path, they can be @@ -747,6 +752,7 @@ impl Server { } #[cfg(feature = "gemini_srv")] + #[doc(cfg(feature = "gemini_srv"))] /// Sets the directory that kochab should look for TLS certs and keys into /// /// Northstar will look for files called `cert.pem` and `key.pem` in the provided @@ -763,6 +769,7 @@ impl Server { } #[cfg(feature = "gemini_srv")] + #[doc(cfg(feature = "gemini_srv"))] /// Set the path to the TLS certificate kochab will use /// /// This defaults to `cert/cert.pem`. @@ -775,6 +782,7 @@ impl Server { } #[cfg(feature = "gemini_srv")] + #[doc(cfg(feature = "gemini_srv"))] /// Set the path to the ertificate key kochab will use /// /// This defaults to `cert/key.pem`. @@ -860,6 +868,7 @@ impl Server { } #[cfg(feature="ratelimiting")] + #[doc(cfg(feature = "ratelimiting"))] /// Add a rate limit to a route /// /// The server will allow at most `burst` connections to any endpoints under this @@ -983,6 +992,7 @@ impl Server { } #[cfg(feature = "scgi_srv")] + #[doc(cfg(feature = "scgi_srv"))] /// Start serving requests on a given unix socket /// /// Requires an address in the form of a path to bind to. This is only available when diff --git a/src/types/body.rs b/src/types/body.rs index ef418a0..c42f7e4 100644 --- a/src/types/body.rs +++ b/src/types/body.rs @@ -27,6 +27,7 @@ pub enum Body { impl Body { /// Called by [`Response::rewrite_all`] #[cfg(feature="scgi_srv")] + #[cfg_attr(docsrs, doc(cfg(feature = "scgi_srv")))] pub (crate) async fn rewrite_all(&mut self, based_on: &crate::Request) -> std::io::Result { let bytes = match self { Self::Bytes(bytes) => { @@ -101,6 +102,7 @@ impl<'a> From<&'a str> for Body { } #[cfg(feature="serve_dir")] +#[cfg_attr(docsrs, doc(cfg(feature = "serve_dir")))] impl From for Body { fn from(file: File) -> Self { Self::Reader(Box::new(file)) diff --git a/src/types/request.rs b/src/types/request.rs index fb9367a..9e49a37 100644 --- a/src/types/request.rs +++ b/src/types/request.rs @@ -209,6 +209,7 @@ impl Request { } #[cfg(feature="scgi_srv")] + #[doc(cfg(feature = "scgi_srv"))] /// View any headers sent by the SCGI client /// /// When an SCGI client delivers a request (e.g. when your gemini server sends a @@ -252,6 +253,7 @@ impl Request { } #[cfg(feature="user_management")] + #[doc(cfg(feature = "user_management"))] /// Attempt to determine the user who sent this request /// /// May return a variant depending on if the client used a client certificate, and if @@ -264,6 +266,7 @@ impl Request { } #[cfg(feature="user_management")] + #[doc(cfg(feature = "user_management"))] /// Expose the server's UserManager /// /// Can be used to query users, or directly access the database diff --git a/src/user_management/mod.rs b/src/user_management/mod.rs index 8dd8a44..52d336a 100644 --- a/src/user_management/mod.rs +++ b/src/user_management/mod.rs @@ -23,6 +23,7 @@ mod manager; #[cfg(feature = "user_management_routes")] mod routes; #[cfg(feature = "user_management_routes")] +#[doc(cfg(feature = "user_management_routes"))] pub use routes::UserManagementRoutes; pub use manager::UserManager; pub use user::User; @@ -71,6 +72,7 @@ pub enum UserManagerError { DeserializeUtf8Error(std::str::Utf8Error), #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] /// There was an error hashing or checking the user's password. /// /// This likely indicates database corruption, and should be handled in the same way @@ -103,6 +105,7 @@ impl From for UserManagerError { } #[cfg(feature = "user_management_advanced")] +#[doc(cfg(feature = "user_management_advanced"))] impl From for UserManagerError { fn from(error: argon2::Error) -> Self { Self::Argon2Error(error) @@ -117,6 +120,7 @@ impl std::error::Error for UserManagerError { Self::DeserializeBincodeError(e) => Some(e), Self::DeserializeUtf8Error(e) => Some(e), #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] Self::Argon2Error(e) => Some(e), _ => None } @@ -139,6 +143,7 @@ impl std::fmt::Display for UserManagerError { Self::DeserializeUtf8Error(e) => write!(f, "Recieved invalid UTF-8 from database, possible corruption: {}", e), #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] Self::Argon2Error(e) => write!(f, "Argon2 Error, likely malformed password hash, possible database corruption: {}", e), } diff --git a/src/user_management/user.rs b/src/user_management/user.rs index bdfa85a..95a9b56 100644 --- a/src/user_management/user.rs +++ b/src/user_management/user.rs @@ -141,6 +141,7 @@ impl NotSignedInUser { } #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] /// Attach this certificate to an existing user /// /// Try to add this certificate to another user using a username and password. If @@ -252,6 +253,7 @@ impl RegisteredUser { } #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] /// Check a password against the user's password hash /// /// # Errors @@ -274,6 +276,7 @@ impl RegisteredUser { } #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] /// Set's the password for this user /// /// By default, users have no password, meaning the cannot add any certificates beyond @@ -364,6 +367,7 @@ impl RegisteredUser { } #[cfg(feature = "user_management_advanced")] + #[doc(cfg(feature = "user_management_advanced"))] /// Check if the user has a password set /// /// Since authentication is done using client certificates, users aren't required to diff --git a/src/util.rs b/src/util.rs index 876b7b3..43ad3a9 100644 --- a/src/util.rs +++ b/src/util.rs @@ -16,6 +16,7 @@ use crate::types::{Document, document::HeadingLevel::*}; use crate::types::Response; #[cfg(feature="serve_dir")] +#[doc(cfg(feature = "serve_dir"))] pub async fn serve_file>(path: P, mime: &str) -> Response { let path = path.as_ref(); @@ -34,6 +35,7 @@ pub async fn serve_file>(path: P, mime: &str) -> Response { } #[cfg(feature="serve_dir")] +#[doc(cfg(feature = "serve_dir"))] pub async fn serve_dir, P: AsRef>(dir: D, virtual_path: &[P]) -> Response { debug!("Dir: {}", dir.as_ref().display()); let dir = dir.as_ref(); @@ -129,6 +131,7 @@ async fn serve_dir_listing, B: AsRef>(path: P, virtual_path } #[cfg(feature="serve_dir")] +#[doc(cfg(feature = "serve_dir"))] pub fn guess_mime_from_path>(path: P) -> &'static str { let path = path.as_ref(); let extension = path.extension().and_then(|s| s.to_str());