docs: add Rustdoc comments and CI support for documentation generation#151
Draft
hyperfinitism wants to merge 2 commits into
Draft
docs: add Rustdoc comments and CI support for documentation generation#151hyperfinitism wants to merge 2 commits into
hyperfinitism wants to merge 2 commits into
Conversation
hyperfinitism
force-pushed
the
docs/rustdoc
branch
3 times, most recently
from
8d724ac to
8b3f29e
Compare
Add module-level documentation (//!) and doc comments (///) to all source files to support `cargo doc` and prepare for `cargo rdme` README generation. Signed-off-by: Takuma IMAMURA <209989118+hyperfinitism@users.noreply.github.com>
Signed-off-by: Takuma IMAMURA <209989118+hyperfinitism@users.noreply.github.com>
hyperfinitism
force-pushed
the
docs/rustdoc
branch
from
8b3f29e to
25965cc
Compare
Member
|
@hyperfinitism is the pr still in draft? |
Contributor
Author
|
Yes. As mentioned in #152, I recognized that this method also has some flaws. In that issue, I proposed several possible approaches. |
This file contains hidden or 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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
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.
This PR replaces #139.
//!) and item-level (///) Rustdoc comments across all source files, socargo docproduces a complete API reference and the crate-level documentation can drive acargo rdme-generatedREADME.md.README.mdfromsrc/main.rs's crate-level doc viacargo rdme. The handwritten sections (overview, basic usage, subcommand table, build/install instructions, reporting bugs) now live as the crate-level doc, keepingcargo docoutput and the rendered README in sync.RustdocCI workflow (.github/workflows/docs.yml) that runs on push and pull request:cargo rdme --check: fails ifREADME.mddiffers from the crate-level doc.cargo doc --no-deps --all-features: fails on broken intra-doc links or other doc-build errors.Build
# cargo install cargo-rdme cargo rdme cargo doc --all-features --no-depsNote
I have left the Asciidoc files as they were. The changes to the adoc files from the preceding PR are not included in this PR.