Use each crate's README as the root module's rustdocs (#460)

At the moment, there is a bit of a gulf between the longer form README documentation we have in the GitHub repo, and the reference documentation shown on `docs.rs` for each crate. I believe this leads to people not really looking at `docs.rs` as much when starting out (particularly if they are less familiar with Rust, so aren't used to checking it by default), making discovery of features and reference examples harder. For example, as seen in: #366 (comment) #402 By using the crate READMEs as the rustdocs for each crate's root module, it means the content will show at the top of the crate's `docs.rs` page - meaning they then show all docs, not just the reference docs. We can then pitch the `docs.rs` page as the best entrypoint for documentation, rather than repo READMEs. As an added bonus, our READMEs will now all be linted for markdown and code correctness (and not only `libcnb-test`'s README). (This is why there are a few changes to the repo root README, to fix lint issues.)
heroku · Jul 7, 2022 · e2ec0e3 · e2ec0e3
1 parent 997a83a
commit e2ec0e3
Show file tree

Hide file tree

Showing 13 changed files with 26 additions and 35 deletions.
diff --git a/README.md b/README.md
@@ -48,13 +48,13 @@ $ rustup target add x86_64-unknown-linux-musl
 #### Docker
 
 If you don't have it already, we need to install Docker. Refer to the Docker documentation on how to install it for your
-operating system: https://docs.docker.com/engine/install/
+operating system: <https://docs.docker.com/engine/install/>
 
 #### pack
 
 To run our buildpack locally, we will use `pack`, a tool maintained by the Cloud Native Buildpacks project to support 
 the use of buildpacks. It's the tool that we will eventually use to run our buildpack and create application images. 
-Find their documentation about installing it here: https://buildpacks.io/docs/tools/pack/
+Find their documentation about installing it here: <https://buildpacks.io/docs/install-pack/>
 
 ### Project Setup
 
@@ -94,9 +94,9 @@ That's all we need! We can now move on to finally write some buildpack code!
 
 ### Writing the Buildpack
 
-As aforementioned, the buildpack we're writing will be very simple. We will just log a "Hello World" message during the build
-and set the default process type to a command that will also emit "Hello World" when the application image is run. 
-Find more complex example buildpacks in the [examples directory](examples).
+The buildpack we're writing will be very simple. We will just log a "Hello World" message during the build
+and set the default process type to a command that will also emit "Hello World" when the application image is run.
+Examples of more complex buildpacks can be found in the [examples directory](https://github.com/heroku/libcnb.rs/tree/main/examples).
 
 Modify the project's `src/main.rs` file to contain the following:
 
@@ -239,6 +239,7 @@ Hello World!
 
 ### Next Steps
 
-While the buildpack we've written in this quick start guide is not very useful, it can serve as a starting point for a 
-more useful buildpack. To discover more of the libcnb API, browse the [examples directory](examples) and the 
-[documentation on docs.rs][docs.rs].
+While the buildpack we've written in this quick start guide is not very useful, it can
+serve as a starting point for a more useful buildpack. To discover more of the libcnb API,
+browse the [examples directory](https://github.com/heroku/libcnb.rs/tree/main/examples)
+and the [documentation on docs.rs][docs.rs].
diff --git a/libcnb-cargo/CHANGELOG.md b/libcnb-cargo/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Fix the packaged buildpack size reported by `cargo libcnb package`. ([#442](https://github.com/heroku/libcnb.rs/pull/442))
 - Reduce number of dependencies to improve installation time. ([#442](https://github.com/heroku/libcnb.rs/pull/442) and [#443](https://github.com/heroku/libcnb.rs/pull/443))
+- Use the crate's `README.md` as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#460](https://github.com/heroku/libcnb.rs/pull/460))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 
 ## [0.4.1] 2022-06-24

diff --git a/libcnb-cargo/src/main.rs b/libcnb-cargo/src/main.rs
@@ -1,4 +1,4 @@
-// https://rust-lang.github.io/rust-clippy/stable/index.html
+#![doc = include_str!("../README.md")]
 #![warn(clippy::pedantic)]
 #![warn(unused_crate_dependencies)]
 // This lint is too noisy and enforces a style that reduces readability in many cases.

diff --git a/libcnb-data/CHANGELOG.md b/libcnb-data/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## [Unreleased]
 
 - Disable `fancy-regex` default features (such as unused unicode support) to reduce buildpack binary size. ([#439](https://github.com/heroku/libcnb.rs/pull/439))
+- Add a crate `README.md` and use it as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#458](https://github.com/heroku/libcnb.rs/pull/458) and [#460](https://github.com/heroku/libcnb.rs/pull/460))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 
 # [0.7.0] 2022-06-24

diff --git a/libcnb-data/src/lib.rs b/libcnb-data/src/lib.rs
@@ -1,10 +1,6 @@
-//! Low-level representations for Cloud Native Buildpack data types.
-
-// Enable rustc and Clippy lints that are disabled by default.
-// https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unused-crate-dependencies
-#![warn(unused_crate_dependencies)]
-// https://rust-lang.github.io/rust-clippy/stable/index.html
+#![doc = include_str!("../README.md")]
 #![warn(clippy::pedantic)]
+#![warn(unused_crate_dependencies)]
 // This lint is too noisy and enforces a style that reduces readability in many cases.
 #![allow(clippy::module_name_repetitions)]
 

diff --git a/libcnb-package/CHANGELOG.md b/libcnb-package/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Strip buildpack binaries when packaging, to reduce buildpack size. This not only reduces the size of production builder images, but also speeds up workflows that involve non-release builds (such as integration tests). ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 - The type of the `cargo_env` argument to `build::build_buildpack_binaries` and `build::build_binary` has changed. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
+- Use the crate's `README.md` as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#460](https://github.com/heroku/libcnb.rs/pull/460))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 
 ## [0.1.2] 2022-06-24

diff --git a/libcnb-package/src/lib.rs b/libcnb-package/src/lib.rs
@@ -1,4 +1,4 @@
-// https://rust-lang.github.io/rust-clippy/stable/index.html
+#![doc = include_str!("../README.md")]
 #![warn(clippy::pedantic)]
 #![warn(unused_crate_dependencies)]
 // This lint is too noisy and enforces a style that reduces readability in many cases.

diff --git a/libcnb-proc-macros/CHANGELOG.md b/libcnb-proc-macros/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Disable `fancy-regex` default features (such as unused unicode support) to reduce buildpack binary size. ([#439](https://github.com/heroku/libcnb.rs/pull/439))
 - Fix `verify_regex`'s error handling when the regex could not be compiled. ([#438](https://github.com/heroku/libcnb.rs/pull/438))
+- Add a crate `README.md` and use it as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#458](https://github.com/heroku/libcnb.rs/pull/458) and [#460](https://github.com/heroku/libcnb.rs/pull/460))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 
 ## [0.2.2] 2022-06-24

diff --git a/libcnb-proc-macros/src/lib.rs b/libcnb-proc-macros/src/lib.rs
@@ -1,8 +1,6 @@
-// Enable rustc and Clippy lints that are disabled by default.
-// https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unused-crate-dependencies
-#![warn(unused_crate_dependencies)]
-// https://rust-lang.github.io/rust-clippy/stable/index.html
+#![doc = include_str!("../README.md")]
 #![warn(clippy::pedantic)]
+#![warn(unused_crate_dependencies)]
 
 use proc_macro::TokenStream;
 use quote::quote;

diff --git a/libcnb-test/CHANGELOG.md b/libcnb-test/CHANGELOG.md
@@ -6,6 +6,8 @@
 - Add `TestConfig::cargo_profile` and `CargoProfile` to support compilation of buildpacks in release mode. ([#456](https://github.com/heroku/libcnb.rs/pull/456))
 - Improve the error message shown when Pack CLI is not installed. ([#455](https://github.com/heroku/libcnb.rs/pull/455))
 - Check that `TestConfig::app_dir` is a valid directory before applying `TestConfig::app_dir_preprocessor` or invoking Pack, so that a clearer error message can be displayed. ([#452](https://github.com/heroku/libcnb.rs/pull/452))
+- Use the crate's `README.md` as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#460](https://github.com/heroku/libcnb.rs/pull/460))
+- Add rustdocs with code examples for all public APIs. ([#441](https://github.com/heroku/libcnb.rs/pull/441))
 - Fix rustdocs for `LogOutput`. ([#440](https://github.com/heroku/libcnb.rs/pull/440))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 

diff --git a/libcnb-test/src/lib.rs b/libcnb-test/src/lib.rs
@@ -1,7 +1,6 @@
-// Enable rustc and Clippy lints that are disabled by default.
-// https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unused-crate-dependencies
+#![doc = include_str!("../README.md")]
+// Enable lints that are disabled by default.
 #![warn(unused_crate_dependencies)]
-// https://rust-lang.github.io/rust-clippy/stable/index.html
 #![warn(clippy::pedantic)]
 // This lint is too noisy and enforces a style that reduces readability in many cases.
 #![allow(clippy::module_name_repetitions)]
@@ -27,9 +26,3 @@ pub use crate::test_runner::*;
 // Suppress warnings due to the `unused_crate_dependencies` lint not handling integration tests well.
 #[cfg(test)]
 use indoc as _;
-
-// This runs the README.md as a doctest, ensuring the code examples in it are valid.
-// It will not be part of the final crate.
-#[doc = include_str!("../README.md")]
-#[cfg(doctest)]
-pub struct ReadmeDoctests;
diff --git a/libcnb/CHANGELOG.md b/libcnb/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 
+- Use the crate's `README.md` as the root module's rustdocs, so that all of the crate's documentation can be seen in one place on `docs.rs`. ([#460](https://github.com/heroku/libcnb.rs/pull/460))
 - Increase minimum supported Rust version from 1.58 to 1.59. ([#445](https://github.com/heroku/libcnb.rs/pull/445))
 
 ## [0.8.0] 2022-06-24

diff --git a/libcnb/src/lib.rs b/libcnb/src/lib.rs
@@ -1,10 +1,6 @@
-//! This crate provides a library to implement [Cloud Native Buildpacks](https://buildpacks.io/).
-
-// Enable rustc and Clippy lints that are disabled by default.
-// https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#unused-crate-dependencies
-#![warn(unused_crate_dependencies)]
-// https://rust-lang.github.io/rust-clippy/stable/index.html
+#![doc = include_str!("../../README.md")]
 #![warn(clippy::pedantic)]
+#![warn(unused_crate_dependencies)]
 // Most of libcnb's public API returns user-provided errors, making error docs redundant.
 #![allow(clippy::missing_errors_doc)]
 // This lint is too noisy and enforces a style that reduces readability in many cases.