Maybe this already exists but I tried to search and didn't find anything so I assume it doesn't (or is, ironically, undocumented). I would like to have some way of including a markdown file or a set (directory) of files to extend the documentation with more in-depth explanations on separate pages.
I'm writing a crate that's a bit more complicated than usual but also not so complicated to require serde.rs-style documentation. I'd prefer to have the extended doc in a separate page generated by rustdoc so that those who already know general ideas and only need to look up e.g. item names are not bothered with tutorial-level documentation.
There are multiple advantages:
All docs in single page, single style people don't have to jump around too much
The doc is included in the source code so anyone can render it locally
Doesn't depend on web-based VCS third parties like github (nothing wrong with github IMO, just nice to not rely on it)
People don't have to worry too much about HTML style/formatting/etc.
Currently making an empty module with documentation seems like the best hack but it's clearly a hack.
Possible disadvantages:
People could abuse it to publish non-crate things but this is already happening and doesn't seem too bad. At least it'd look nicer.
Added complexity. I think it shouldn't be too bad, all the things required are already in rustdoc, they just have to be rewired appropriately.
People could be confused and accidentally put there things that belong to API documentation. However people can write bad or even missing doc already, so it's not a good argument.
As a user I don't have a strong opinion one way or another, but to share an example of prior art, HexDocs is the equivalent of rustdoc for the Elixir ecosystem and is powered by the ExDoc library, and authors may include "Guide" pages to offer things like tours, tutorials, and prose explanations around practices.
As a specific example I think the documentation for the Absinthe package capitalized on it nicely, as it offers a lot of instructive content that don't intuitively relate directly to specific code modules. Including it there rather than on a bespoke, separate documentation site means the other features of the documentation, such as interlinking, are still readily available.
FWIW, docs-rs already has a separate documentation page from the API docs. I think it'd be useful to have an officially supported place to put "guide-level"/"book" documentation within the cargo doc ecosystem, but I also think that having the API documentation clearly separate from the guide documentation (though both can and should cross-link) is useful.
It's kind of sad that doxidize died off. (Though I'm glad that rustdoc got easier enough to contribute to that it could die off!) In a perfect world, doxidize could've been that tool. From its design docs:
Many Rust users love Rustdoc, so why change the way it works? The core reason is this:
Rustdoc is designed for API documentation, and does a great job of it. But there's more to docs than just API docs. Doxidize is built to consider all forms of documentation your project needs.
This perspective means that Doxidize has to make several different decisions from rustdoc . Namely, while rustdoc has just barely grown to understand documentation written outside of Rust source, Doxidize was built around this idea. This means that the API docs adapt to the more general needs of docs, rather than fitting all docs into API docs.
There's some previous issues about integrating mdBook into either of rustdoc or docs.rs that are probably relevant.
I do somewhat feel like being able to include single markdown pages (not a tree of pages, only as leaf pages below an existing item) might be useful enough as a middleground to support; in addition to having the ability for more complex mdBook backed documents.
Things on the list needed for clap (independent of the implementation details, like using mdBook):
Intra-doc links:
The derive reference makes many references to parts of the clap API that would be helped by being able to link
Each of the traits that can be derived link to the derive reference and we need a maintainable way of keeping this (we don't put the documentation on the traits because its large and cross-cutting)
Sourcing external files (speaking of mdBook). Clap's documentation has large examples that need more testing than standard rustdoc tests can provide. Our md pages that would be pulled in with this proposal currently link out to those files. This isn't ideal today and, depending on how this proposal is implemented, those links would then break. Of course bringing along the .rs files is a stopgap but the ideal is sourcing them like you can do in mdBook. Having seen serde's mdBook documentation, I'm assuming they'd get value from this as well.
