feat: add pro-forma libaray to allow feature documentation of gitoxide on docs.rs

Author: Byron

Cargo.toml

@@ -25,6 +25,48 @@ doctest = false
 [features]
 default = ["max"]
 
+#! ### Build Configuration
+#! These combine common choices of building blocks to represent typical builds.
+
+## Everything, all at once.
+##
+## As fast as possible, with TUI progress, progress line rendering with auto-configuration, all transports based on their most mature implementation (HTTP), all `ein` tools, CLI colors and local-time support, JSON output, regex support for rev-specs.
+max = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line", "prodash-render-tui", "prodash/render-line-autoconfigure", "gix/regex" ]
+
+## Like `max`, but only Rust is allowed.
+##
+## This is the most compatible build as it won't need a C compiler or C toolchains to build. It's also not the fastest as or the most feature-rich in terms of available
+## transports as it uses Rust's HTTP implementation.
+##
+## As fast as possible, with TUI progress, progress line rendering with auto-configuration, all transports available but less mature pure Rust HTTP implementation, all `ein` tools, CLI colors and local-time support, JSON output, regex support for rev-specs.
+max-pure = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "prodash-render-tui", "gix/max-performance-safe", "gix/comfort", "http-client-reqwest", "gitoxide-core-blocking-client", "gitoxide-core-tools", "prodash/render-line-autoconfigure", "gix/regex" ]
+
+## All of the good stuff, with less fanciness for smaller binaries.
+##
+## As fast as possible, progress line rendering, all transports based on their most mature implementation (HTTP), all `ein` tools, CLI colors and local-time support, JSON output.
+lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
+
+## The smallest possible build, best suitable for small single-core machines.
+##
+## This build is essentially limited to local operations without any fanciness.
+##
+## Optimized for size, no parallelism thus much slower, progress line rendering.
+small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal"  ]
+
+## Like lean, but uses Rusts async implementations for networking.
+##
+## This build is more of a demonstration showing how async can work with `gitoxide`, which generally is blocking. This also means that the selection of async transports
+## is very limited to only HTTP (without typical `git` configuration) and git over TCP like provided by the `git daemon`.
+##
+## As fast as possible, progress line rendering, less feature-ful HTTP (pure Rust) and only `git-damon` support, all `ein` tools, CLI colors and local-time support, JSON output.
+##
+## Due to async client-networking not being implemented for most transports, this one supports only the 'git+tcp' and HTTP transport.
+## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
+lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]
+
+#! ### Building Blocks
+#! Typical combinations of features of our dependencies, some of which are referred to in the `gitoxide` crate's code for conditional compilation.
+
 ## Makes the crate execute as fast as possible by supporting parallel computation of otherwise long-running functions
 ## as well as fast, hardware accelerated hashing, along with a faster zlib backend.
 ## If disabled, the binary will be visibly smaller.
@@ -39,36 +81,24 @@ pretty-cli = [ "gitoxide-core/serde", "prodash/progress-tree", "prodash/progress
 ## that appears after a short duration.
 prodash-render-line-crossterm = ["prodash-render-line", "prodash/render-line-crossterm", "prodash/signal-hook", "is-terminal", "crosstermion"]
 
-#! ### Convenience Features
-#! These combine common choices of the above features to represent typical builds
-
-## *fast* + *prodash-render-tui-crossterm* + *prodash-render-line-crossterm* + *http* + *gitoxide-core-tools* + *client-networking*
-max = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line", "prodash-render-tui", "prodash/render-line-autoconfigure", "gix/regex" ]
-
-## *fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-networking*.
-lean = ["fast", "pretty-cli", "http-client-curl", "gitoxide-core-tools-query", "gitoxide-core-tools", "gitoxide-core-blocking-client", "prodash-render-line" ]
-## fast* + *prodash-render-line-crossterm* + *gitoxide-core-tools* + *client-async-networking*.
-## Due to async client-networking not being implemented for most transports, this one supports only the 'git' transport.
-## It uses, however, a fully asynchronous networking implementation which can serve a real-world example on how to implement custom async transports.
-lean-async = ["fast", "pretty-cli", "gitoxide-core-tools", "gitoxide-core-tools-query", "gitoxide-core-async-client", "prodash-render-line"]
-
-## As small as it can possibly be, no threading, no fast sha1, line progress only, rust based zlib implementation.
-## no networking, local operations only.
-small = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "is-terminal"  ]
+## Progress reporting with a TUI, can then be enabled with the `--progress` flag.
+prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
 
-## Makes the crate execute as fast as possible without pulling in C libraries, while keeping everything else minimal akin to the `small` build.
-max-pure = ["pretty-cli", "gix-features/rustsha1", "gix-features/zlib-rust-backend", "prodash-render-line", "prodash-render-tui", "gix/max-performance-safe", "gix/comfort", "http-client-reqwest", "gitoxide-core-blocking-client", "gitoxide-core-tools", "prodash/render-line-autoconfigure" ]
+## Progress reporting by visually drawing lines into the terminal without switching to an alternate window.
+prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]
 
-#! ### `gitoxide-core` Configuration
+## Prints statistical information to inform about cache efficiency when those are dropped.
+## Use this as a way to understand if bigger caches actually produce greater yiedls.
+cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]
 
-##  A way to enable all `gitoxide-core` tools found in `gix tools`
+##  A way to enable most `gitoxide-core` tools found in `ein tools`, namely `organize` and `estimate hours`.
 gitoxide-core-tools = ["gitoxide-core/organize", "gitoxide-core/estimate-hours"]
 
-## A program to perform analytics on a git repository, using an auto-maintained sqlite database
+## A program to perform analytics on a `git` repository, using an auto-maintained sqlite database
 gitoxide-core-tools-query = ["gitoxide-core-tools", "gitoxide-core/query"]
 
-#! #### Mutually Exclusive Networking
-#! If both are set a compile error is triggered. This also means that `cargo … --all-features` will fail.
+#! ### Building Blocks for mutually exclusive networking
+#! If some of these are set at the same time a compile error is triggered. This also means that `cargo … --all-features` will fail.
 
 ## Use blocking client networking.
 gitoxide-core-blocking-client = ["gitoxide-core/blocking-client"]
@@ -79,10 +109,6 @@ http-client-reqwest = ["gix/blocking-http-transport-reqwest-rust-tls"]
 ## Use async client networking.
 gitoxide-core-async-client = ["gitoxide-core/async-client", "futures-lite"]
 
-# internal
-prodash-render-tui = ["prodash/render-tui", "prodash/render-tui-crossterm", "prodash/progress-tree", "futures-lite"]
-prodash-render-line = ["prodash/render-line", "prodash-render-line-crossterm", "prodash/progress-tree"]
-cache-efficiency-debug = ["gix-features/cache-efficiency-debug"]
 
 [dependencies]
 anyhow = "1.0.42"

README.md

@@ -145,6 +145,9 @@ effortlessly and for your particular CPU for additional performance gains.
 The minimum supported Rust version is [documented in the CI configuration](https://github.com/Byron/gitoxide/blob/main/.github/workflows/msrv.yml#L23),
 the latest stable one will work as well.
 
+There are various build configurations, all of them are [documented here](https://docs.rs/crate/gitoxide/latest). The documentation should also be useful
+for packagers who need to tune external dependencies.
+
 ```
 # A certain way to install `gitoxide` with just Rust and a C compiler installed.
 # If there are problems with SSL certificates during clones, try to omit `--locked`.

src/lib.rs

@@ -0,0 +1,24 @@
+//! This is the documentation of the binaries that come with `gitoxide`. These are called…
+//!
+//! #### `gix`
+//!
+//! A developer tool to allow using `gitoxide` algorithms and functionality outside of the test suite. It will be unstable as long as
+//! the `gix` crate is unstable and is explicitly not to be understood as `git` replacement.
+//!
+//! #### `ein`
+//!
+//! A program to eventually become the most convenient way to do typical operations on `git` repositories, with all tooling one typically
+//! needs built right into it.
+//! For now, it's most useful for its assorted set of `tools` which help to build automations or learn something about `git` repositories.
+//!
+//! ## Feature Flags
+//!
+//! Feature configuration can be complex and this document seeks to provide an overview.
+//!
+#![cfg_attr(
+    feature = "document-features",
+    cfg_attr(doc, doc = ::document_features::document_features!())
+)]
+#![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
+#![deny(rust_2018_idioms, missing_docs)]
+#![forbid(unsafe_code)]