Python Documentation: MkDocs vs Sphinx

Creating documentation is one of the most important things you can do as a developer. You’ll need to document not only your code, but also how the application works, and maybe even system specifications.

Thankfully, we have tools at our disposal so that we don’t need to create a giant word doc and spend time formatting it. Instead, we can use code natively to generate our documentation!

Here, we’ll be exploring MkDocs and Sphinx and the pros and cons of using both packages to show you how to create python documentation.

Understanding and Using Sphinx

Sphinx is a tool that makes it easy to create intelligent and beautiful documentation, originally created for the Python documentation. This tool has grown to become the standard tool for documenting Python projects.

Key features of Sphinx

Here’s a few key features that differ from MkDocs:

• Auto-Documentation from Docstrings: Sphinx can automatically generate documentation from the docstrings in source code. This is particularly useful for developers, as it helps to ensure that the documentation remains up-to-date with the codebase, with minimal additional effort required to update it.

• Support for Multiple Output Formats: Sphinx can produce documentation in multiple formats from the same source, including HTML, PDF, and ePub, making it versatile for different distribution needs.

Getting Started with Sphinx

To install sphinx, you can either use pip or conda:

pip install -U sphinx

conda install -c conda-forge sphinx

Then to get started, navigate to your project directory and run the following command. You’ll be prompted with information to provide the project name, author(s), and whether if you want to use certain features:

sphinx-quickstart

Generating Documentation with Sphinx

To include Python modules in the documentation, you’ll need to leverage .rst (reStructuredText) files. For example, our index.rst file (which is automatically created by the sphinx-quickstart command:

.. My Project documentation master file, created by sphinx-quickstart.
   Welcome to My Project's documentation!
   ==================================================

   Introduction
   ------------

   Welcome to the documentation for My Project. Here you will find information on how to utilize the project and details on the internal workings of the code.

   Table of Contents
   -----------------

   .. toctree::
      :maxdepth: 2
      :caption: Contents:

      installation
      usage
      modules
      api_reference
      faq

   Indices and tables
   ------------------

   * :ref:`genindex`
   * :ref:`modindex`
   * :ref:`search`

In our toctree (or table of contents tree), we have installation, usage, modules, api_reference, and faq. Each of these are their own individual .rst file, which may look something such as:

Installation Guide
==================

To install My Project, you can simply use pip:

.. code-block:: bash

    pip install myproject

Ensure you have Python 3.x installed on your system before installing My Project.

Auto API Documentation

One of the largest advantages of Sphinx over MkDocs is how you can auto-generate API documentation. This saves lots of time and all you need to do is include the .. automodule:: directive:

Modules
=======

.. automodule:: my_module
   :members:

For more details regarding autodoc, please visit the Sphinx documentation.

Your project’s success starts with the right domain.

Whether you’re a beginner launching your first Flask app or an experienced developer scaling Django sites, SiteGround makes it simple to secure the ideal domain name.

With SiteGround, you’ll be able to find and lock in the perfect domain name in seconds, effortly manage DNS settings and domain renewals, and keep your personal information secure with free WHOIS privacy.

Register your domain today and get a discount on your first purchase!

Understanding and Using MkDocs

MkDocs is a fast, simple static site generator that's geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.

Key Features of MkDocs

Here are a few key features of MkDocs that differ from Sphinx:

• Markdown Support: MkDocs uses Markdown as its primary markup language, making it accessible for those familiar with basic writing in Markdown. This lowers the barrier for content creators who may not be familiar with more complex markup languages like reStructuredText.

• Realtime Preview Capabilities: MkDocs includes a live preview feature that automatically rebuilds your documentation when files are changed.

Getting Started with MkDocs

To get started, run the following command to install it with pip:

pip install mkdocs

Then, to start a new project:

mkdocs new my-project

Navigate into that directory and start the documentation:

cd my-project
mkdocs serve

Generating Documentation with MkDocs

To create documentation with MkDocs, you’ll create Markdown (.md) files and modify your mkdocs.yml file to configure your project.

For example, your mkdocs.yml file may look as such:

site_name: My Project
nav:
    - Home: index.md
    - Installation: installation.md
    - Usage: usage.md
    - API Reference:
        - Module 1: api_module1.md
        - Module 2: api_module2.md
    - FAQ: faq.md
theme: readthedocs

In case you’re not familiar with Markdown, here’s a cheat sheet for you to use.

» Unlike Sphinx, MkDocs allows you to view the documentation as you update it when you run the mkdocs serve command.

Feature Comparison: MkDocs and Sphinx

Taking a look at features both packages have side by side, we see that Sphinx does have some advantages over MkDocs, and vice versa:

So, to answer the question of “which should I use?”, you should make this decision based off of what your project needs. Both documentation generators have their advantages and disadvantages.

I personally use MkDocs for my documentation, as it’s quicker to stand up and deploy.