Different crate docs for public API and internals documentation

help
1

Normally mycrate/src/lib.rs has the toplevel documentation for the crate's public API. Here I like to put an introduction to what the crate does, an example, etc.

I build two documentation sites, the normal one for the public API, and one with cargo doc --document-private-items for the internals. I like to point new contributors to the internals documentation (plus, it is SO NICE to get internals docs right there in your text editor thanks to rust-analyzer!).

Is it possible to have the internals documentation present different contents in the toplevel than what is shown for the public API? For the internals, I'd like the toplevel to have a description of the library's architecture, or pointers to interesting places in the code - info only of interest to people working on the crate's code.

That is, can I do something so that cargo doc and cargo doc --document-private-items make it as if src/lib.rs had different //! contents?

1 Like
2

Why not simply place internals doc in an empty top-level module? For example, see the cookbook and tutorials modules in the csv crate.

3

I like that scheme, thank you!

4

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.