Rustbook - a tool similar to rustdoc, but for writing books

ppl really like writing whole books in their docs, and as a workaround for that we decided to give them the external doc attribute.

this is a mistake. it would be better to create a rustbook tool for making books with embedded tests. it would also give it better UI and UX than rustdoc.

things like DSL specification, regex string description, etc should be embedded into the source, not as a separate file. python ppl really like putting the regex module documentation separate from the regex module and I see it as a huge mistake because it actually makes the regex module less commented than it should be.

there is a benefit to specifying an external filename tho - translated docs. but it wouldn't be used instead of the in-source docs, but in addition to. and the untranslated docs would still be in-source.

see also: https://github.com/rust-lang/rust/issues/44732#issuecomment-535995303 and https://github.com/rust-lang/rust/issues/44732#issuecomment-536005509

Have you seen mdBook? It doesn't support PDF or ePUB export yet though.