rust-lang / rust-lang/docs.rs

Add a secondary mode with --document-private-items

Open
#304 16 comments 11 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-builds C-enhancement E-medium uses-more-storage
Dominant language
Rust
Stars
1.2k
Forks
232
Avg merge
11h 35m
Merged PRs (30d)
60

Description

Context

Often, the internal parts of a crate have their own documentation, even if they're not exposed as part of the public API. It can be pretty useful to be able to have a rendered version of that documentation for reference and development purposes:

  • the doc comments are rendered as text in a way that may be nicer to read;
  • the docs are linkable, making it easy to share references to specific items' docs with collaborators;
  • the rustdoc interface can show highlights of the internal structure (e.g., all trait implementations in one place);
  • the internal documentation may be of independent interest.

For instance, a bunch of notes on the internal details of a crypto implementation I wrote are kept in documentation for internal modules, hosted separately from the "external" docs. Although that's probably an extremal example in terms of "effort put into documentation of private items", I think this would still be useful ecosystem-wide.

Proposal

docs.rs could render documentation for all crates twice, once as normal and once with --document-private-items, then host a second copy of the documentation for all crates under a different URL. Each set of docs would link internally to itself, so following links in the "public" section would remain in the "public" section, and following links in the "private" section would remain in the "private" section.

I'm not attached to this in particular, but my suggestion would be to place all private docs on a separate subdomain, say private.docs.rs, with an identical URL structure to the "public" docs.rs. The advantage of this choice is that:

  • it's really easy to switch between internal and external docs by adding or removing the subdomain;
  • it's clear from looking at the URL bar which version you're seeing, even if the full path is too long to display.

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 docs.rs's crate-rendering flow and how rustdoc handles --document-private-items. Define the separate private-doc URL or subdomain and ensure public and private documentation link within their own section. Done means crates are rendered in both modes and the second copy is addressable with the same URL structure.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.