Getting a RTD Started for Git Repo

The following is a minimalist guide to getting a Readthedocs page. Most of your documentation should be in .rst documents, where this guide will show how to add figures, math, and code blocks.

Note

I’m a rookie at RTD, and willing to learn. Happily accepting all constructive criticisms on how to make things better!

Your Code Documentation

Your documentation blocks should also follow the .rst, here are some examples for Python objects and functions. For purposes of the tutorial, let core.py be the following:

MyClass:
    """
    Description
    -----------

    Class that has attributes and methods.

    Attributes
    -----------
        name : str
            Name of the concerning party.
        value : int
            Value of the transaction.

    Methods
    -------
    __init__(self,name,value)
        Initializes the class object.
    mymethod(self,x)
        Multiplies the argument x by 10.
    """
    def __init__(self,name,value):
        self.name = name
        self.value = value

    def mymethod(self,x):
        """
        Description
        -----------
        Multiplies x by 10.

        Parameters
        -----------
        x : float
            Quantity to multiply by 10.

        Returns
        -------
        float
            The quantity x multiplied by 10.
        """
        return 10 * x

def myfunc(y):
    """
    Description
    -----------
    Adds 5 to y

    Parameters
    ----------
    y : float or int
        Quantity to add 5.

    Returns
    -------
    int or float
        The quantity y plus 5.
    """
    return y + 5

The Repository and Configuration

First, Structure your repository according to the following structure:

  • main
    • myreponame
      • myreponame

        • core.py

        • util.py

      • docs
        • media

          • landing_page_image.png

      • tests

      • …

      • README.md

Your source code for the package your making documentation for should be in the main/myreponame/myreponame directory. Go ahead and fire up a command prompt or terminal. From your <path>/myreponame directory,

pip install sphinx
cd docs
sphinx-quickstart

This will create a conf.py file and index.rst. My default configuration for the conf.py is shown below

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import sys
import os
sys.path.insert(0, os.path.abspath('../myreponame'))
sys.path.insert(0, os.path.abspath('../..'))
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('.'))

project = 'myreponame'
copyright = '2024, My Institution or Organization'
author = 'First Last, First Last, First Last'  #If multiple Authors
release = '0.0'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
# You may add other extensions to this list as required.

extensions = [
    'sphinx.ext.duration',
    'sphinx.ext.doctest',
    'sphinx.ext.autodoc',
    'sphinx.ext.autosummary',
    'sphinx.ext.intersphinx',
    'sphinx.ext.mathjax'
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']



# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']
html_logo = 'media/gtlogo.png'

# Common modules that used, add more as necessary.
autodoc_mock_imports = ['numpy', 'scipy', 'matplotlib']

For purposes of this tutorial, I recommend replacing the content of the autogenerated conf.py with the above.

Note

If you use any packages within your code modules, i.e., core.py, they must be added to the autodoc_mock_imports or the readthedocs build will fail.

Ensure you change the myreponame to yours. A typical configuration for my index.rst is as follows:

Welcome to the documentation for myreponame
============================================

.. image:: media/landing_page_image.png

**myreponame** is a Python library intended to do stuff.

Check out the :doc:`setup_and_installation` section for further information, including
how to install the project.

.. note::

   This project is under active development.

Contents
--------

.. toctree::
    :maxdepth: 2
    :caption: Getting Started

    setup_and_installation

.. toctree::
    :maxdepth: 2
    :caption: Functional Blocks

    functional_blocks

.. toctree::
    :maxdepth: 2
    :caption: Tutorials:

    tutorials/firsttutorial
    tutorials/secondtutorial

The files setup_and_installation.rst, functional_blocks, and the ones within the tutorial directory are user-created and fairly standard components of the documentation. For example setup_and_installation.rst,

Installation
=============

.. _installation:

To use radar, first install it using pip (Same for Windows and Linux):

.. code-block:: console

    git clone https://github.com/username/myreponame.git
    cd myreponame
   (.venv) $ pip install ./

and functional_blocks.rst, I’ll use something like the following to list out all documentation for objects and functions within my code. For example, my project might have two modules util.py and core.py, see the project structure from earlier for their location. core.py was described explicitly here, do not feel compelled to create filler documentation util.py, just creating the file is sufficient. The automodule block will parse the """ documentation blocked sections and build an html page based on that .rst within the documentation block. This doesn’t always work perfectly, and may require some configuring.

myreponame.util
===========
\..\ automodule:: myreponame.util
    :members:
    :undoc-members:
    :exclude-members: __dict__, __weakref__, __module__

myreponame.core
===========
\..\ automodule:: myreponame.core
    :members:
    :undoc-members:
    :exclude-members: __dict__, __weakref__, __module__

Note

The proper syntax is actually .. automodule::, but needs to be this way to work as non-executable .rst here.

Building the Project

Go ahead and create a tutorials directory and provide two .rst files within firsttutorial and secondtutorial. You may add to these later, but just so they fit the template outline before. At this point you can do an intial build from the myreponame/docs folder

make html

If successful, this will create a folder _build. You can you the resultant documentation page _build/html/index.html. Feel free to explore this a little bit to get a feel for how the .rst files produce the project structure.

You can add more to your tutorial directory files to experiment with math or other markup:

.. math::

    f_1(\alpha) + g_2(\beta) = 1

Hosting on Readthedocs

  1. Create a readthedocs account https://about.readthedocs.com/ and link your Git account. This did not work with Georgia Tech’s LDAP Git…

  2. Add a requirements.txt file in main/myreponame/docs. It can be barebones as literally one word, but you need this nonetheless.

..code-block:

sphinx

  1. Add file within the main/myreponame level of your project, .readthedocs.yaml

version: "2"

build:
  os: "ubuntu-22.04"
  tools:
    python: "3.10"

python:
  install:
    - requirements: docs/requirements.txt

sphinx:
  configuration: docs/conf.py

  1. Go to builds under that project and click build version. If all goes well you should be able to View Docs.

If you see something no quite right with your page but go no error, check the raw build log back on the builds page.