Rust documentaiton layout

1

There are few features I like in documentation and I do not know how to get them with cargo rust doc

  1. How does one get the location of the current page, relative to the entire documentation tree, on the left side margin and the headings within the current page on the right side margin. For example; see
    begin_cmd - xrst documentation

  2. How does one have two levels of documentation. One, for uses, that defines the package API and that just links within itself. Another, for developers, that automatically includes and can link to all the user documentation.

  3. How does one turn off the documentation of some public items (that are not part of the user API) when building the user documentation and turn it on when building the developer documentation.

2

Not sure, but you may be looking for how to reference and link to a module, which links to the top of the page for that module. That's done with [module-path]. For example, [self] will link to the current module. See
https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html

Other than the answer below, I don't know of any options for this.

With --document-private-items. See
https://doc.rust-lang.org/rustdoc/write-documentation/the-doc-attribute.html#hidden

3

I have a particular case in mind now. There is a sub-module that is public because it defines some constants that are used elsewhere. The entire module is an implementation detail and not part of the API. I want to include its documentation for the developer and hide it form the user. How do I do this ?

4

Assuming you want the docs.rs docs to be the user-facing docs, i.e. hide the module from these docs, you can add the following to your Cargo.toml:

[package.metadata.docs.rs]
rustdoc-args = ["--cfg", "docsrs"]

to add the docsrs conditional compilation flag to docs.rs builds of your documentation.

Then, hide the module from the docs if the docsrs flag is enabled:

#[cfg_attr(docsrs, doc(hidden))]
mod foo;

This is not specific to docs.rs, you can use compiler flags or Cargo features in a way that suits your doc build pipeline.

5

Sorry, I meant to mention #[doc(hidden)] above. You could try that for modules. For an entire module you may need to use #![doc(hidden)] (note the !) at the top of the module. See:
https://doc.rust-lang.org/rustdoc/write-documentation/what-to-include.html#what-to-exclude

6

#![doc(hidden)] does hide the module when I use cargo doc but what command do I use to include the hidden documentation ?

cargo doc --document-private-items does not seems to include the hidden module (for me) ?

7

There is --document-hidden-items but it is unfortunately unstable.

RUSTDOCFLAGS='-Zunstable-options --document-hidden-items' cargo +nightly doc
8

At the project directory level, I use the bin sub-directory for scripts that help maintain a the project. I added the bin/doc_hidden.sh script (below) so that I would not need to use the unstable version of rust. This only works for files that have been checked into the git repository.

if [ "$0" != "bin/doc_hidden.sh" ]
then
   echo "bin/doc_hidden.sh: must be executed from its parent directory"
   exit 1
fi
#
# pattern
pattern='^ *#\[doc(hidden)\] *$'
list=$( git grep -l "$pattern" )
for file in $list
do
   mv $file $file.bak
   sed -e "/$pattern/d" $file.bak > $file
done
cargo doc
for file in $list
do
   mv $file.bak $file
done
echo 'bin/doc_hidden.sh: OK'

P.S. #[doc(hidden)] seems to work for me.

9

In the script above, I had to change cargo doc to cargo doc --document-private-items to get what I consider to be the developer documentation.

10

It seems that if I change some of my pub declarations to pub(crate) I do not need the #[doc(hidden)] commands. In fact, this is really better (for my purpose).