Consider using mdbook's include anchors feature for some examples
Nobody has claimed this yet.
- Dominant language
- CSS
- Stars
- 2.3k
- Forks
- 325
- PR merge metrics
- No merged PRs in 30d
Description
@ehuss suggested in https://github.com/rust-lang/nomicon/pull/288#pullrequestreview-696730664:
One possible option in the future is to use
{{#rustdoc_include}}(along with mdbook's include anchors), and place the sample code in a separate directory where it can be more thoroughly tested. I notice there are huge chunks of code that aren't tested at all, which means there is a good likelihood that it contains errors, or may become incorrect in the future. TRPL is written this way. A big downside is that it becomes more difficult to edit/read the markdown source since the examples are in a separate file, so it is tough to decide if that is worth it.
I think at least examples using libc crate should be considered here. They're ignored just because requiring an external crate but it would be easy to test if we had it.
And some longer examples could also be moved to the external directory to shrink markdown files.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the linked review on pull request 288 and inspect the Nomicon markdown examples, especially ignored examples using the libc crate and longer code blocks. Determine which examples should move to a separate directory and how mdbook include anchors could expose them; done means the selected examples are included in the documentation and can be thoroughly tested.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- rust
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 30/100