Read the Docs integration for sphinx-apidoc

Introduction

In Previous post, I described how to execute both sphinx-apidoc and sphinx with one command. However, this method was not the method of changing the behavior of setuptools itself, but with services such as Read the Docs that runs sphinx directly without biting setuptools. There was a problem that it could not work well. In this post, I will describe how to incorporate sphinx-apidoc directly into the execution on the sphinx side.

procedure

The directory structure etc. conforms to Last Post.

First, include sphinx-apidoc in your Sphinx run.

doc/source/conf.py

import sphinx.apidoc


root_dir = os.path.abspath('../..') 

try:
    # This succeeds = the project is already installed.
    # This directive avoids Readthedocs to fail
    import my_project
except ImportError:
    sys.path.insert(0, root_dir)
    import my_project

# ...
# Rest of the conf.py
# ...


def run_apidoc(_):
    script_dir = os.path.dirname(os.path.realpath(__file__))
    src_dir = os.path.join(script_dir,  root_dir)
    out_dir = os.path.join(script_dir, "modules")
    sphinx.apidoc.main(
        ['', '-f', '-H', project, '-A', author,
         '-V', version, '-R', release, '-T', '-M',
         '-o', out_dir, src_dir])


def setup(app):
    app.connect('builder-inited', run_apidoc)

There are two points:

1. Try ʻimport my_project`, and if it fails, try importing again through the path to the root of the project. This is because Read the Docs builds the library once, installs it in the local environment, and then builds the documentation [^ 1].
2. Hook the execution of sphinx-apidoc when Sphinx is executed by defining the setup command.

[^ 1]: This is an option for Read the Docs, not the default behavior. However, if you have defined dependent libraries on the setuptools side, I think it's smarter than creating a separate requirements.txt for Read the Docs.

If you have installed sphinx-apidoc in setup.py as in the previous post, restore it to its original state. Then, modify around setup.py as follows.

setup.py

cmdclass = {} 

#Otherwise you will need Sphinx just to install the library as a user
try:
    from sphinx.setup_command import BuildDoc
    cmdclass['build_sphinx'] = BuildDoc
except ImportError:
    pass

# ...
# Rest of the setup.py
# ...

setup(
   ...
   cmdclass=cmdclass
)

setup.cfg

[build_sphinx]
source-dir = doc/source
build-dir  = doc/build
all_files  = 1

Finally, set the Read the Docs side.

By following the above steps, you can build the documentation in the development environment with python setup.py build_sphinx, and you can build in the same way from Read the Docs.