mkdocs¶

TL;DR: Making documentation for your package is vital, using mkdocs makes that step much easier.

Making documentation is vital to the success of your package. If you do not add documentation, not only will no one else understand what you have done, you will not understand what you've done in two years time.

There are a few tools to help you make websites/documentation for your tools. Personally, I find mkdocs makes pretty documentation, and has the easiest to remember commands. For me, it's the easiest tool. However, you might prefer other tools, like sphinx.

Do I have to?¶

Yep.

What counts as documentation?¶

Documentation could be inline comments in your code to explain what you're doing and why. Documentation is also docstrings in your functions and classes. These are helpful (read: crucial) for users to understand how to interact with your functions and classes. Documentation is also README files, webpages, and tutorials. You should do at least some of these!

How do I do it with minimal effort?¶

This is where mkdocs comes in! mkdocs will turn your docstrings into a nice website for you.

Here's how I would go about making documentation

1. Add docstrings to all your functions.¶

When I make a new function, for example

def add_ten(x):
    return x + 10

I now need to document the function. I like the numpy docstring style, so I would document like this

def add_ten(x):
    """
    Function to add 10 to an input

    Parameters
    ----------
    x : int, float
        Input value

    Returns
    -------
    result : int, float
        x + 10
    """
    return x + 10

This is overkill for a small function, but the key parts are 1. a short description (which can go into a longer description if needed) 2. A list of the parameters 3. A list of the objects that get returned.

2. Install and start a mkdocs project¶

First off, to install mkdocs you will need to install the following (here I'm using poetry!)

poetry add -D mkdocs mkdocs-material mkdocstrings
poetry add -D pytkdocs -E numpy-style

This will install mkdocs, the mkdocs-material style, and will let you parse docstrings in the numpy style used above.

To use mkdocs you will need to first make a project using

poetry run mkdocs new .

This will create a docs directory, and a mkdocs.yml file.

3. Alter the mkdocs.yml and markdown files.¶

First, the mkdocs.yml file is where you're going to specify some key parts about your docs:

site_name: my_package
nav:
    - Home: index.md
    - API: api.md

theme:
  name: "material"
repo_url: https://github.com/SSDataLab/my_package
plugins:
  - search
  - mkdocstrings:
      default_handler: python
      handlers:
        python:
          selection:
            docstring_style: "numpy"
          rendering:
            show_source: false
      custom_templates: templates
      watch:
        - src/my_package

Here we're telling mkdocs that we want a single homepage, we want to use the "material" theme, and we want to automatically build the documentation for the docstrings using the numpy style.

The next piece we need is index.md. You will find this file in your docs/ directory. This is a simple markdown file, which you can change to add some simple docs. You can make this a copy of your README file if you like, or you can add some extra detail on your package like install instructions.

Finally you'll need something like a markdown file for your package docs. Here docs/api.md may look like

# Documentation for `BackDrop`

::: tess_backdrop.BackDrop
    handler: python
    selection:
      members:
        - BackDrop
        - load
        - build_correction
        - fit_model
        - save
    rendering:
      show_root_heading: false
      show_source: false

Here I have a class called BackDrop in my package tess_backdrop. I tell mkdocs this is a Python tool, and then ask for it to document the class BackDrop, and the methods load, build_correction, fit_model and save.

4. Build your doc pages!¶

This is the fun part. Now you've made these files you can see what your docs will look like. You can use

poetry run mkdocs serve

To start a local version of your docs page. Navigate your browser to http://127.0.0.1:8000/ to see the docs. This is "live", if you change the markdown files you've built, it will automatically update this website.

Once you're happy with your docs, you can "deploy" them.

poetry run mkdocs gh-deploy

This command will build your docs, and push them to your gh-pages branch on your GitHub repo. This is a special branch, which is used to create your docs. (Note: you may need to check a box in the settings of your repo for it to use gh-pages automatically https://github.com/SSDataLab/my_package/settings/pages)

You should now be able to navigate to

username.github.io/my_package

And see your docs live! For example, check out https://ssdatalab.github.io/tess-backdrop, which has automatic API documentation using this workflow

There are other plugins for mkdocs!¶

For example, you can get a plugin which will run and render jupyter notebooks in your docs!

In [ ]: