Creating Docs for a package and Uploading it to Pypi

Create docs using sphnix

Sphinx is a python package that takes in bunch of .rst (reStructuredText markup) and creates beautiful (and standardized) HTML pages to serve as the documentation for your project.

The HTML files ultimately become the webpages, and can either be hosted on github pages, or conventionally on readthedocs.org.

install sphinx

First, you need to install sphinx that will handle file formats and conversions for you.

You can install it using pip install sphinx

But my personal prefernce is to create a docs conda environment that I activate anytime I want to work on all things documentations

conda create -n docs -y sphinx
conda activate docs

Now sphinx is installed and ready to go.

Initialize the docs

Now in the base of the toolbox you want to create the docs for, start the whole process by initialize some boilerplate docs files

sphinx-quickstart docs

You can now accept the default settings, that does not separate your docs rst from your built html, does not require any prefixes, and takes in a project name myproject for example.

If you have good docstrings, sphinx might be able to import them and start working with them if you are lucky, otherwise you'll have to do it manually.

Once everything is done, you'll see (among others) a conf.py, an index.rst, and a Makefile files in the docs directory.

• conf.py contains configuration of your docs, such as project names, license, and author names, as well themes and templates.
• index.rst contains the landing page of your docs, for example mvcomp firstlevel page.
• Makefile is what sphinx will use to create html files.

We will be editing the first two, and never touching the last one.

conf.py

Go ahead and start filling what you think you can fill in the conf.py file. This is pretty straight forward.

One thing you can change here is the theme. the default conf comes with the alabaster which is quite nice but not what is widely used.

You can easily change the theme to readthedocs default by setting it in conf.py:

import sphinx_rtd_theme 
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
html_static_path = ['_static']

Check the mvcomp conf.py if you need more information

index.rst

This index is the landing page of your entire documentation, so it must contain the paths to all other indecies for the uses to navigate the website.

A simple and clean one will include indices of all subpages, such as the mvcomp one:

.. include:: FirstLevel/index.rst 

.. toctree::
    :maxdepth: 1
    :caption: Table of Contents
    :hidden:

    FirstLevel/index.rst
    UserGuide/index.rst
    Contributing/index.rst

Here, the include parameter points to what will be shown on this page (in this instance is it the text in FirstLevel/index.rst.

However, you can just populate this however you want, and include the text directly here.

toctree is the tree of the table contents, which is the navigation menu of the site. If you set the default to maxdepth to 1, then only the high level items will show. These items are (duh) the first level items such as FirstLevel, UserGuide, and Contributing (not limited to these, you can create as many as you want.

Each of these items is a subdirectory, with an index file. For instance, mvcomp UserGuide is a directory of 4 pages, each illustrating a use case of the toolbox.

Make as many subdirectory, their indices, and their pages as you want as long as you include their indices in the first index.rst one. You package my be simpler or more complex.

mvComp first level has only an index, containing a lot of text on how to install and cite. It has 4 use cases in the user guide, therefore it contains 4 pages plus an index. Its contributing guide is text based, so it has one index file of text.

Requirements for building on readthedocs

You docs must have a requirement.txt file for readthedocs to be able to install necessary packages and build the cite.

In the base directory of the docs, create a requirements.txt with the theme name at the very least, and populate as necessary.

Mvcomp only needs two packages, the theme and the tomli package to parse text configuration files. Start with these two, and see if you need anything else depending on your use case.

Configuration for building on readthedocs

In the base directory of your project (NOT THE DOCS), create a .readthedocs.yaml file that will house all the configuration for building.

It will contain the sphinx version required, the OS to use for building, and paths to the conf.py and requirements.txt files you just created. Start simple, like the mvcomp yaml config, and expand as needed.

I never managed to get the pdf conversion to work for me, but I did not need it. If you manage to do get it working, update this guide!!

The yaml file should look something like this

# Required
version: 2
# Set the OS, Python version and other tools you might need
build:
  os: ubuntu-22.04
  tools:
    python: "3.10"
# Build documentation in the docs/ directory with Sphinx
sphinx:
  configuration: docs/conf.py

# Optionally set the version of Python and requirements required to build your docs
python:
   install:
      - requirements: docs/requirements.txt

Build the html

Once everything is good to go, open the terminal to the docs directory and run make html.

This will trigger sphinx to make the html files, and put them in _build/html. If you have vscode installed, you can install the live server plugin and go in the index.html file and start a server. You should be able to see the webpage rendered properly on a localhost on your machine.

Package your python toolbox and make it available on Pypi

Pypi is a public repository of python software, that make it easy to install packages using pip.

There are several standards to using Pypi, and the world of python developement is wide and scary.

Here's what I have found to be the necessary knowledge base.