# Rust documentaiton layout

**URL:** <https://users.rust-lang.org/t/rust-documentaiton-layout/130496>\
**Category:** uncategorized\
**Created:** [June 8, 2025, 11:29am UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496 "2025-06-08T11:29:19Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 8, 2025, 11:29am UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/1 "2025-06-08T11:29:19Z")

</div>

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](https://xrst.readthedocs.io/latest/begin_cmd.html)

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.

---

<div class="post-metadata">

**Author:** ![jumpnbrownweasel](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/jumpnbrownweasel/32/17403_2.png) [@jumpnbrownweasel](https://users.rust-lang.org/u/jumpnbrownweasel)\
**Post date:** [June 8, 2025, 4:33pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/2 "2025-06-08T16:33:41Z")

</div>

> [@bradbell](#):
>
> - 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](https://xrst.readthedocs.io/latest/begin_cmd.html)

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](https://doc.rust-lang.org/rustdoc/write-documentation/linking-to-items-by-name.html)

> [@bradbell](#):
>
> - 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.

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

> [@bradbell](#):
>
> 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.

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

---

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 9, 2025, 4:31pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/3 "2025-06-09T16:31:55Z")

</div>

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 ?

---

<div class="post-metadata">

**Author:** ![jofas](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/jofas/32/30690_2.png) [@jofas](https://users.rust-lang.org/u/jofas)\
**Post date:** [June 9, 2025, 4:41pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/4 "2025-06-09T16:41:41Z")

</div>

> [@bradbell](#):
>
> How do I do this ?

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`:

```rust
[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:

```rust
#[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.

---

<div class="post-metadata">

**Author:** ![jumpnbrownweasel](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/jumpnbrownweasel/32/17403_2.png) [@jumpnbrownweasel](https://users.rust-lang.org/u/jumpnbrownweasel)\
**Post date:** [June 9, 2025, 4:43pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/5 "2025-06-09T16:43:05Z")

</div>

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](https://doc.rust-lang.org/rustdoc/write-documentation/what-to-include.html#what-to-exclude)

---

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 9, 2025, 5:59pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/6 "2025-06-09T17:59:20Z")

</div>

`#![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) ?

---

<div class="post-metadata">

**Author:** ![kpreid](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/kpreid/32/22420_2.png) [@kpreid](https://users.rust-lang.org/u/kpreid)\
**Post date:** [June 9, 2025, 7:52pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/7 "2025-06-09T19:52:49Z")

</div>

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

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

```

---

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 9, 2025, 8:32pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/8 "2025-06-09T20:32:48Z")

</div>

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.

```rust
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.

---

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 10, 2025, 1:03am UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/9 "2025-06-10T01:03:39Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![bradbell](https://avatars.discourse-cdn.com/v4/letter/b/e95f7d/32.png) [@bradbell](https://users.rust-lang.org/u/bradbell)\
**Post date:** [June 10, 2025, 3:10pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/10 "2025-06-10T15:10:10Z")

</div>

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).

---

<div class="post-metadata">

**Author:** ![system](https://sea1.discourse-cdn.com/flex019/user_avatar/users.rust-lang.org/system/32/51372_2.png) [@system](https://users.rust-lang.org/u/system)\
**Post date:** [September 8, 2025, 3:10pm UTC](https://users.rust-lang.org/t/rust-documentaiton-layout/130496/11 "2025-09-08T15:10:44Z")

</div>

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.