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

Header Image
How to build rusqlite on Windows

Yesterday I spent way more time than needed for compiling this dependency on Windows. The problem is that the error was not informative enough and hard to google, and, mostly, that there is …

Header Image
Most Promising Programming Languages of 2017

Another year, another 5 promising programming languages you should keep an eye on in 2017. As usual, I’d like to write the warning I put here every year: in this list, you will not find …

Header Image
How to use Rust in Python (Part 3)

You can follow the links to read the first part and the second part of this series. In the previous part we have seen how to pass not trivial data to Rust functions such as a Python list. It …

comments powered by Disqus