rust-lang / rust-lang/rustc-dev-guide

rustdoc: Restructure all rustdoc-related chapters

Open
#2,459 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-cleanup C-enhancement T-rustdoc
Dominant language
HTML
Stars
1.9k
Forks
612
Avg merge
17h 24m
Merged PRs (30d)
39

Description

  1. Chapters about rustdoc's test suites shouldn't live in rustdoc-internals/ but in tests/ where all other test-related things are located.
  2. The split between "rustdoc overview" and "rustdoc internals" is weird, "I don't know where to put things".
  3. The "rustdoc overview" (in "How to build in run the compiler") contains a lot of things, a lot of things. It's not really an overview / a succinct but complete intro on how to get things going.
  4. Then we have "internals" as well which IIRC duplicates some of the info given in the "overview" / mentions things that should be in an "overview" idk

Disclaimer: My memory is slightly hazy, these were my thoughts / mere feelings from ~1 week ago when I worked on https://github.com/rust-lang/rustc-dev-guide/pull/2298. I prolly didn't read everything as carefully as I could because I worked on other things but I remember being slightly frustrated / confused with the overall structure of rustdoc-related information etc.

I know this isn't very actionable right now, these comments come straight out of my mind, unprocessed. I'll revisit this at some point.

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 by reviewing the rustdoc-related chapters in rustdoc-internals/, tests/, and the rustdoc overview under "How to build in run the compiler," including the changes discussed in PR #2298. Map duplicated and misplaced content before proposing a new structure; done means the chapters have clear, non-overlapping locations and the guide's navigation reflects that structure.

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
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.