-
Notifications
You must be signed in to change notification settings - Fork 69
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Simplify doc management and update READMEs #208
Conversation
Also as a side bonus, README examples are not compilable, which makes it easier to track outdated code. |
Signed-off-by: Maksym Pavlenko <[email protected]>
Signed-off-by: Maksym Pavlenko <[email protected]>
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I looked but I didn't see where the docs get compiled on a PR, is it cargo doc
that passes the feature?
@@ -14,12 +14,11 @@ | |||
limitations under the License. | |||
*/ | |||
|
|||
#![cfg_attr(feature = "docs", doc = include_str!("../README.md"))] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
does this need the `//!`` so it formats properly?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No, we can include markdown directly here.
You can verify the final result with:
cargo doc --no-deps --features docs --open
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
cool!
Signed-off-by: Maksym Pavlenko <[email protected]>
I've updated CI to verify readmes with Github actions. The [package.metadata.docs.rs]
features = ["docs"] |
LGTM |
Currently we manage root documentation for each crate in 2 places: crate's README.md on Github and module's root documentation (comments that start with
//!
) that gets uploaded to docs.rs. Typically this is the same text that needs to be present in 2 places.This PR aims to simplify this flow and uses README.md in both places, so there is no need to sync docs. When building, each crate will use
include_str!="README.dm"
macro to include the latest docs from the file.I avoid extra work on local environments, this feature is hidden behind
docs
toggle, which is automatically enabled when building documentation for docs.rs.