rust-lang / rust-lang/nomicon

Consider using mdbook's include anchors feature for some examples

Open
#289 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-meta
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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.