From 53ef76e29f5b458a44baedbf6052da7cdeef06c2 Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Mon, 8 May 2023 01:45:42 +0200 Subject: [PATCH] refactor: rust docs features metadata --- Cargo.toml | 1 + Makefile | 15 +++++++++++++-- docs/content/building-from-source.md | 2 +- src/lib.rs | 24 ++++++++++++++++++++++++ src/settings/cli.rs | 5 +++++ src/settings/file.rs | 2 ++ src/settings/mod.rs | 2 +- 7 files changed, 47 insertions(+), 4 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index f8eb850..cbc68fa 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -26,6 +26,7 @@ autoexamples = true [package.metadata.docs.rs] all-features = true +rustc-args = ["--cfg", "docsrs"] [lib] name = "static_web_server" diff --git a/Makefile b/Makefile index f092fec..5e7b04c 100644 --- a/Makefile +++ b/Makefile @@ -252,10 +252,17 @@ crate-docs: .PHONY: crate-docs crate-docs-dev: - @cargo doc --no-deps + @env \ + RUSTFLAGS="--cfg docsrs" \ + RUSTDOCFLAGS="--cfg docsrs" \ + cargo doc --lib --no-deps --all-features --document-private-items @echo "Crate documentation: http://localhost:8787/static_web_server" @static-web-server -p 8787 -d target/doc/ \ - & watchman-make -p 'src/**/*.rs' --run 'cargo doc' + & watchman-make -p 'src/**/*.rs' --run '\ + env \ + RUSTFLAGS="--cfg docsrs" \ + RUSTDOCFLAGS="--cfg docsrs" \ + cargo doc --lib --no-deps --all-features --document-private-items' .PHONY: crate-docs-dev docs-deploy: @@ -284,6 +291,10 @@ docs-deploy: @git checkout master .PHONY: docs-deploy +typos: + @typos . --config ./.github/workflows/config/typos.toml +.PHONY: typos + man: @asciidoctor --doctype=manpage --backend=manpage docs/man/static-web-server.1.rst .PHONY: man diff --git a/docs/content/building-from-source.md b/docs/content/building-from-source.md index 037be78..ee29f7f 100644 --- a/docs/content/building-from-source.md +++ b/docs/content/building-from-source.md @@ -28,7 +28,7 @@ However, you can disable just the ones you don't need from the lists below. Feature | Description ---------|------ -**Deafult** | +**Default** | `default` | Activates all features by default. [**HTTP2/TLS**](./features/http2-tls.md) | `http2` | Activates the HTTP2 and TLS feature. diff --git a/src/lib.rs b/src/lib.rs index e6aa663..936f02c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -67,12 +67,32 @@ //! - Ability to accept a socket listener as a file descriptor for use in sandboxing and on-demand applications (E.g [systemd](http://0pointer.de/blog/projects/socket-activation.html)). //! - Cross-platform. Pre-compiled binaries for Linux, macOS, Windows and FreeBSD (`x86`,`x86_64`,`ARM`,`ARM64`). //! +//! ## Cargo features +//! +//! When building from the source, all features are enabled by default. +//! However, you can disable just the ones you don't need from the lists below. +//! +//! Feature | Description +//! ---------|------ +//! **Default** | +//! `default` | Activates all features by default. +//! [**HTTP2/TLS**](https://static-web-server.net/features/http2-tls/) | +//! `http2` | Activates the HTTP2 and TLS feature. +//! `tls` | Activates only the TLS feature. +//! [**Compression**](https://static-web-server.net/features/compression/) | +//! `compression` | Activates auto-compression and compression static with all supported algorithms. +//! `compression-brotli` | Activates auto-compression/compression static with only the `brotli` algorithm. +//! `compression-deflate` | Activates auto-compression/compression static with only the `deflate` algorithm. +//! `compression-gzip` | Activates auto-compression/compression static with only the `gzip` algorithm. +//! `compression-zstd` | Activates auto-compression/compression static with only the `zstd` algorithm. +//! #![deny(missing_docs)] #![forbid(unsafe_code)] #![deny(warnings)] #![deny(rust_2018_idioms)] #![deny(dead_code)] +#![cfg_attr(docsrs, feature(doc_cfg))] // Extern crates #[macro_use] @@ -83,8 +103,10 @@ extern crate serde; // Public modules pub mod basic_auth; #[cfg(feature = "compression")] +#[cfg_attr(docsrs, doc(cfg(feature = "compression")))] pub mod compression; #[cfg(feature = "compression")] +#[cfg_attr(docsrs, doc(cfg(feature = "compression")))] pub mod compression_static; pub mod control_headers; pub mod cors; @@ -105,6 +127,7 @@ pub mod settings; pub mod signals; pub mod static_files; #[cfg(feature = "tls")] +#[cfg_attr(docsrs, doc(cfg(feature = "tls")))] pub mod tls; pub mod transport; #[cfg(windows)] @@ -113,6 +136,7 @@ pub mod winservice; pub mod error; // Private modules +#[doc(hidden)] mod helpers; // Re-exports diff --git a/src/settings/cli.rs b/src/settings/cli.rs index 2053fd1..a50ac5c 100644 --- a/src/settings/cli.rs +++ b/src/settings/cli.rs @@ -144,20 +144,24 @@ pub struct General { env = "SERVER_HTTP2_TLS" )] #[cfg(feature = "http2")] + #[cfg_attr(docsrs, doc(cfg(feature = "http2")))] /// Enable HTTP/2 with TLS support. pub http2: bool, #[structopt(long, required_if("http2", "true"), env = "SERVER_HTTP2_TLS_CERT")] #[cfg(feature = "http2")] + #[cfg_attr(docsrs, doc(cfg(feature = "http2")))] /// Specify the file path to read the certificate. pub http2_tls_cert: Option, #[structopt(long, required_if("http2", "true"), env = "SERVER_HTTP2_TLS_KEY")] #[cfg(feature = "http2")] + #[cfg_attr(docsrs, doc(cfg(feature = "http2")))] /// Specify the file path to read the private key. pub http2_tls_key: Option, #[cfg(feature = "compression")] + #[cfg_attr(docsrs, doc(cfg(feature = "compression")))] #[structopt( long, short = "x", @@ -169,6 +173,7 @@ pub struct General { pub compression: bool, #[cfg(feature = "compression")] + #[cfg_attr(docsrs, doc(cfg(feature = "compression")))] #[structopt( long, parse(try_from_str), diff --git a/src/settings/file.rs b/src/settings/file.rs index 2de11dc..97e11a7 100644 --- a/src/settings/file.rs +++ b/src/settings/file.rs @@ -118,10 +118,12 @@ pub struct General { /// Compression. #[cfg(feature = "compression")] + #[cfg_attr(docsrs, doc(cfg(feature = "compression")))] pub compression: Option, /// Check for a pre-compressed file on disk. #[cfg(feature = "compression")] + #[cfg_attr(docsrs, doc(cfg(feature = "compression")))] pub compression_static: Option, /// Error 404 pages. diff --git a/src/settings/mod.rs b/src/settings/mod.rs index c616489..1d60d2e 100644 --- a/src/settings/mod.rs +++ b/src/settings/mod.rs @@ -13,7 +13,7 @@ use structopt::StructOpt; use crate::{Context, Result}; -mod cli; +pub mod cli; pub mod file; #[cfg(windows)] -- libgit2 1.7.2