Use each crate's README as the root module's rustdocs #460
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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.)
edmorley
added
documentation
edmorley
force-pushed
the
edmorley/readmes-as-module-docs
branch
from
d6837d2 to
de8dcd5
Compare
Malax
approved these changes
Jul 7, 2022
edmorley
added a commit
that referenced
this pull request
Jul 14, 2022
Followup to #460. Previously it was referencing the repo root file, which doesn't exist when the package is published (since at that point it's no longer in a monorepo). Now, the package root `README.md` is used instead, which is a symlink to the repo root `README.md` in the monorepo, and when the package is published is the resolved README from: https://github.com/heroku/libcnb.rs/blob/3c9637e238d23d3fec402f27c81fa8a13b1a5a6d/libcnb/Cargo.toml#L11-L12 The redundant doctest readme include has also been removed. GUS-W-11395978.
edmorley
added a commit
that referenced
this pull request
Jul 14, 2022
Followup to #460. Previously it was referencing the repo root file, which doesn't exist when the package is published (since at that point it's no longer in a monorepo). Now, the package root `README.md` is used instead, which is a symlink to the repo root `README.md` in the monorepo, and when the package is published is the resolved README from: https://github.com/heroku/libcnb.rs/blob/3c9637e238d23d3fec402f27c81fa8a13b1a5a6d/libcnb/Cargo.toml#L11-L12 The redundant doctest readme include has also been removed. GUS-W-11395978.
edmorley
added a commit
that referenced
this pull request
Jul 20, 2022
Previously the rustdocs for the `libcnb::data` module were auto-generated, and resulted in: ``` ## Modules build Provides build phase specific types and helpers. data libcnb-data Docs Latest Version MSRV ... ``` (where the "Docs Latest Version MSRV" are broken badge links from `libcnb-data`'s README) Now the content from the libcnb-data README is overridden, which results in: ``` ## Modules build Provides build phase specific types and helpers. data Provides types for CNB data formats. Is a re-export of the `libcnb-data` crate. ... ``` Follow-up to #460.
edmorley
added a commit
that referenced
this pull request
Jul 20, 2022
Previously the rustdocs for the `libcnb::data` module were auto-generated, and resulted in: ``` ## Modules build Provides build phase specific types and helpers. data libcnb-data Docs Latest Version MSRV ... ``` (where the "Docs Latest Version MSRV" are broken badge links from `libcnb-data`'s README) Now the content from the libcnb-data README is overridden, which results in: ``` ## Modules build Provides build phase specific types and helpers. data Provides types for CNB data formats. Is a re-export of the `libcnb-data` crate. ... ``` Follow-up to #460.
edmorley
added a commit
that referenced
this pull request
Sep 23, 2022
For parity with the other crates, after: #460
edmorley
added a commit
that referenced
this pull request
Sep 26, 2022
For parity with the other crates, after: #460
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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.rsfor each crate.I believe this leads to people not really looking at
docs.rsas much when starting out (particularly if they are less familiar with Rust, so aren't used to checkingdocs.rsout of habit), 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.rspage - meaning that thedocs.rspage then shows all docs, not just the reference docs. We can then pitch thedocs.rspage (rather than repo READMEs) as the best entrypoint for documentation - a "one stop shop" for docs if you will.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.)GUS-W-11395978.