Learn to customize the rust-docs page

[kianenigma]

So that we can hack it a bit to look more custom made.

Also, there are a few hacks that if we find answers to, we can use:

1. https://github.com/paritytech/polkadot-sdk/issues/191
2. Make it show tests, examples, and so on
3. Easier distinction between types that are storage and not.
4. Easier distinction between enums and struct that are part of pallet macros and those that are not.
5. Easier distinction between functions that are getters.
6. Easier distinction between functions that are dispatchables.

Some of these are being handled in an https://github.com/paritytech/substrate/tree/kiz-improve-fast-unstake-dcos, but in hacky ways.

Some ideas from GPT-4:

Rustdoc is a tool that generates documentation for Rust projects from doc-comments within the source code. While the default rendering is sufficient for most use-cases, you might want to customize it to better suit your needs or preferences. Here are a few hacks to tweak the rendering of Rustdocs:

Custom CSS:
You can add custom CSS to change the appearance of the generated documentation. Create a new CSS file, and include it in your Cargo.toml under the [package.metadata.docs.rs] section:

toml
Copy code
[package.metadata.docs.rs]
rustdoc-args = ["--html-in-header", "path/to/your/custom.css"]
Now you can add any CSS rules to the custom file to modify the appearance of the Rustdoc output.

Custom JavaScript:
If you need more advanced control over the rendering, you can add custom JavaScript to the generated docs. Create a new JavaScript file and include it in your Cargo.toml as well:

toml
Copy code
[package.metadata.docs.rs]
rustdoc-args = ["--html-in-header", "path/to/your/custom.js"]
With JavaScript, you can reorder sections, hide or show elements, or make other changes to the DOM as needed.

Modify the theme:
Rustdoc has a built-in theme switcher. You can create a custom theme by modifying the theme CSS files located in the src/librustdoc/html/static/themes directory in the Rustdoc source code. You can then include your custom theme in your project, allowing users to switch to it using the theme switcher.

Custom HTML templates:
Rustdoc uses Handlebars templates to generate the HTML output. You can create your own templates to customize the structure of the generated documentation. You'll need to modify the Rustdoc source code, located in the src/librustdoc/html directory, and then build a custom version of Rustdoc to use with your project.

Fork Rustdoc:
If you need extensive customization, you can fork the Rustdoc project, make your desired changes, and use your custom Rustdoc version to generate documentation for your projects. This approach allows you to have full control over the output and functionality but requires more effort to maintain and stay up-to-date with the official Rustdoc releases.

Remember that making significant changes to the appearance or structure of Rustdocs can make it harder for other Rust users to navigate and understand your documentation. Be cautious with customizations and consider the impact on usability before implementing them.

[kianenigma]

both --scrape-exmaples and --scrape-tests unstable features seem interesting; see: https://github.com/rust-lang/cargo/issues/10865

[kianenigma]

What I mean by

Easier distinction between types that are storage and not.

Is something like the deprecated tag here, but for storage.

[sam0x17]

We might even be able to do this with some very clever CSS media queries without even needing to inject js, in the event that docs.rs blocks custom js but allows css

[sam0x17]

Ok it does indeed work on docs.rs: https://docs.rs/docs_js_injection_test/latest/docs_js_injection_test/

Problem is, I have yet to figure out how to get this same trick to work on local cargo doc, but will see what I can find

[kianenigma]

https://crates.io/crates/doc_item/0.3.0 is pretty amazing.