Very often, one wants to place a deluge of documentation into a particular module. I'm pretty sure that as it stands, all of this documentation needs to live in //! comments inside of the source code. From a programming perspective, however, I have very often had to scroll past hundreds of lines of documentation that was mostly irrelevant to the source code itself but was collocated with the source code because it was paramount for it to appear in the module. This is also bad for source code changes; whenever I make a lot of changes to a particular file's documentation, it might look like I have made a lot of changes to the actual functionality of the module... until I read the commit message and see something like "added a tutorial and three examples".
Because of this I've very often gotten into the habit of writing a lot of documentation in exterior markdown files and then linking to these files in the module's documentation but usually it saddens me that the documentation is one more step removed from the module it is related to.
Further: even the lengthy introductions of modules that will usually find themselves in doc comments inside of the source files is a bit of a drag to scroll through. So, in accordance to the title: is there a way to "include" arbitrary markdown into documentation via rust-doc? And if not, is this considered useful enough that it should be included in the rust-doc utility? Because it is possible that the way things are right now encourages a lot more discipline and structure: keep module documentation to a minimum and lengthy excursions into tutorials or philosophy should be relegated to external markdown files. And normally I follow this, but there is an interesting middle ground that I think gets neglected: documentation that should necessarily appear inside of the module, but is long enough to distract from the code and also cause "noise" in commit chains.