Repository navigation
Conversation
| $ rustdoc src/lib.rs --crate-name mycrate --crate-list-heading="Dependencies" | ||
| ``` | ||
|
|
||
| By default, the crate appears under a catch-all "Crates" heading. |
There was a problem hiding this comment.
This is not what my implementation actually does (and I don’t think it should be changed this way, either). Rather, all crates are still under “Crates”, and the user-specified headings are sub-headings of “Crates”. The uncategorized crates merely lack the sub-heading and appear directly under “Crates”.
There was a problem hiding this comment.
A visual difference between these, besides the heading font size, is that as implemented, if all crates have headings specified, then the first user-specified heading will appear under “Crates”, rather than replacing “Crates” as this text implies.
| [ExDoc CLI]: https://github.com/elixir-lang/ex_doc#cli | ||
|
|
||
| ## Unresolved questions | ||
| [unresolved-questions]: #unresolved-questions |
There was a problem hiding this comment.
One thing the feature as described lacks is a way to sort headings distinctly from their text. If this turns out to be desired, we might need to change the CLI further, and that might be something to do before stabilization, depending on the exact design. (One way to accomplish this would be to add a second, independent CLI option for the sort key, which would be non-breaking.)
Users who want specific sorting can already add prefixes (0-9, A-Z) to the headings, but that takes up significant space in the narrow width of the sidebar.
| ## Unresolved questions | ||
| [unresolved-questions]: #unresolved-questions | ||
|
|
||
| Does `--crate-list-heading=""` work? |
There was a problem hiding this comment.
I lean towards saying it should be allowed (and equivalent to not specifying the option), because having a default value that can’t be expressed as an explicit value makes callers’ lives harder for no particular great benefit.
|
|
||
| Does `--crate-list-heading=""` work? | ||
|
|
||
| What happens when you compile the same doc twice, once with a heading and once without? |
There was a problem hiding this comment.
I would expect this to move the crate to the new position, just like any other change to a previously documented crate overwrites the old info, but I am not deeply familiar with how rustdoc operates in this area.
Describes rust-lang/rust#138143, an unstable feature,
which we will need to RFC before stabilizing.
Adds a way to group sidebar crate entries in Rustdoc into headers.
Important
Since RFCs involve many conversations at once that can be difficult to follow, please use review comment threads on the text changes instead of direct comments on the RFC.
If you don't have a particular section of the RFC to comment on, you can click on the "Comment on this file" button on the top-right corner of the diff, to the right of the "Viewed" checkbox. This will create a separate thread even if others have commented on the file too.
Rendered