Readthedocs does not display docstring documentation

Question

I have followed the getting started guide on Readthedocs and have used Sphinx using autodoc to create the documentation for my Python package on https://github.com/akdiem/bloodflow. (documentation relevant .rst files are in the docs folder)

The readthedoc build passed and is found on https://bloodflow.readthedocs.io/en/latest/

Readthedocs does not show any of the docstring documentation that is part of my code, but to me everything looks like it should. Why does it not?

Crappie

If it helps anyone else coming here, I had the same issue and turning off my ad-blocker when viewing my live docs solved it... – Grasmere

Answer 1

Autodoc is a Sphinx extension that looks at its automodule directive references in .rst files during build time, imports and identifies Python code and then converts their docstrings into html.

Since your module is not installed into the environment with a setup.py, It needs to import your module manually so you need to give sphinx context in conf.py:

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

In this case, the absolute path to your top module is 2 levels above the conf.py file.

After this you can add your autodoc directive file arteryfe.rst back to index.rst toctrees and it should be showing up.

Welcome to artery.fe's documentation!
=====================================

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

    arteryfe
    getting_started
    tutorial
    theory
    numerical

In the case you ever want to make an environment installation, you'll have to tick the option for ReadTheDocs to use a virtualenvironment and utilize site-packages.

---

Addendum:

This is another way to do it and is particularly useful if you have more than one package.

Manually creating files with Autodoc directives can be problematic in larger codebases, so we have Sphinx Apidoc - it is an extension complementing the Autodoc extension.

This means that you may run sphinx-apidoc with the preferred options and it will generate .rst files from your Docstrings with the automodule directives - which will then generate into html. However this can also be done through conf.py during build time in RTD.

For instance, this would have Sphinx generate an automodule arteryfe.rst file in /source/_autogen during build time:

import os
import sys
#Location of Sphinx files
sys.path.insert(0, os.path.abspath('./../..'))

import sphinx.apidoc
def setup(app):
    sphinx.apidoc.main(['-f', #Overwrite existing files
                        '-T', #Create table of contents
                        #'-e', #Give modules their own pages
                        '-E', #user docstring headers
                        #'-M', #Modules first
                        '-o', #Output the files to:
                        './source/_autogen/', #Output Directory
                        './../arteryfe', #Main Module directory
                        ]
    )

After that just glob all the autogen output into your toctree.

Welcome to artery.fe's documentation!
=====================================

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

    getting_started
    tutorial
    theory
    numerical

.. toctree::
    :maxdepth: 2
    :glob:
    :caption: Code:

    _autogen/*

It a bit less flexible since making templates for apidoc is complicated. It is still a valid solution and useful in some cases (i.e. huge codebases).

I've scribbled an RTD compatible Example here for apidoc multipackages.

Mathieu