Building documentation in RTD using a makefile

Question

I created a package for sagemath and used Sphinx to create its documentation. Now I'm trying to create the necessary configuration files to build the documentation in readthedocs.

The problem is that I've come across is that in order for the documentation to build, I have to run sphinx inside a sagemath shell (that is, sage -sh -c "make html").

Is there any way to achieve so with the configuration file for readthedocs? Or to use a makefile to build the docs? Can't seem to find the information on their documetation.

user_554319 · Answer

At the moment, Read the Docs has a fixed build process that involves calling python -m sphinx -b html (with some more parameters) from the virtual environment where the requirements are installed. This is described in the documentation.

Therefore, running custom commands is not possible.

However, since sage is available from conda and Read the Docs supports conda environments, you might be able to build the docs without invoking a Sage shell.

user_2187091 · Answer

Read the Docs has released a beta feature that allows users to override the build process completely and execute custom commands. You can achieve what you want by using build.commands config key in the configuration file (see https://docs.readthedocs.io/en/stable/config-file/v2.html)

Full documentation of this beta feature at https://docs.readthedocs.io/en/stable/build-customization.html#override-the-build-process

Building documentation in RTD using a makefile

2 Answers