Documenting projects with MkDocs

When you have to document a project you are working on, you always have at least two targets: developers looking for understanding the code and its architecture and end users that just want to use it.

The documentation for the first target is usually easy to handle, you can document carefully the source code and use a tool that auto generates the documentation such as Swagger, Apidoc, Javadoc, etc.

The second target is more complicated to handle by developers, it’s not automatic and we have to use a less schematic and more descriptive language. Fortunately, there are tools that help us to write this kind of documentation. MkDocs is a good one.

MkDocs is a really simple static site generator that is focused on building project documentation. Its main features are:

• Source files are written in Markdown.
• Only needs a simple and small YAML configuration file.
• Themeable: It has built-in responsive themes, including one for Read The Docs, and allows you to write your own.
• Text search.
• Built-in webserver with auto reload: Just edit and save your files and you will see instantly the changes in the browser.
• Command to deploy to GitHub pages and works out-of-the-box with Read The Docs and PyPI.

Using MkDocs is so easy that you can learn how to use it just reading its home page in 2 minutes. In fact, the MkDocs home page is generated with MkDocs, as well as Django Rest Framework. Tom Christie, the author of both projects, is eating his own dog food.

Despite all these great features, MkDocs may not be the best tool for your project. Markdown has some limitations so if you need to write huge, complex and/or scientific documentation, you probably should use something like Sphinx or Asciidoctor.

Use the right tool for the right job.