Mastodon Icon GitHub Icon LinkedIn Icon RSS Icon

How to add a logo in Rust documentation

Header image for How to add a logo in Rust documentation

One of the feature I like the most on Rust is automatic documentation. Documentation is a pillar in language ergonomic, and I love that Rust spend so much time into making documentation and documenting code a much pleasant experience.

Rust autogenerated documentation (with cargo doc) looks good, every crate on get its documentation published on, and, most important, every code example in the code is compiled and run as a “unit test” making sure that all the examples are up-to date!

I love that. But what if we want to customize a bit the documentation? For instance, by uploading a crate logo or a custom favicon? Googling this does not provide a lot of information. That’s why I am writing this small how to.

The #![doc] attribute

I started looking for a solution to this problem by watching the documentation of iron. That’s cool! I want it too!

The solution is very simple. In your main source file, add this line at the very beginning of the file:

#![doc(html_logo_url = "path_to_logo", html_favicon_url = "path_to_favicon")]

It is simple as that!

This is the desired output!
Figure 1. This is the desired output!

More documentation for this amazing attribute can be found here.

The #![deny(missing_docs)] attribute

As a final bit, this is another attribute I like a lot. This forces me to put documentation in every public function. You know… I am a diligent developer… but I am like Haskell: lazy by default. It is a good thing to have the compiler yelling at me! :D

comments powered by Disqus