How to set up multiple Sphinx documents in one project in ReadTheDocs?

Question

I would like to use ReadTheDocs to host my Sphinx documentation. The project is hosted on github. I can connect to it just fine.

The particularity that I have is that the project contains 2 Sphinx documents (e.g. a programmer's manual and a user's manual). ReadTheDocs appears to be detecting both (there are two conf.py) and building both. However when it comes to displaying them, it displays the html for only one of them, as far as I can make it, the first one alphabetically.

So my questions are:

1. If both have been built, how do you get to see the other one?

2. Is there a way to use "subprojects" to specify the path to each conf.py and hence have clear URL to each document/manual? That would be the ideal solution.

Phalan

Answer 1

Read the Docs does not support building two different sets of documentation from the same repository and same Read the Docs project. However, you could use sphinx-multiproject extension to achieve this.

You will need to define this extension in your requirements (see https://docs.readthedocs.io/en/stable/guides/specifying-dependencies.html) and then import your repository twice under Read the Docs --one time per set of documentation you want to host: mydocs-users and mydocs-developers, for example.

Note that this is the exact pattern that Read the Docs itself uses for its documentation:

• User's documentation: https://docs.readthedocs.io/
• Developer's documentation: https://dev.readthedocs.io/

The repository for both sets of documentation is the same (https://github.com/readthedocs/readthedocs.org/) but documentation generated on each of the projects is defined by that sphinx-multiproject extension. See https://github.com/readthedocs/readthedocs.org/blob/6bf0bede7b757f1e9458e29ba89b591389cae4d5/docs/conf.py#L48-L63

Trope

Answer 2

Be sure you follow the tutorial.

Usually you need an index (in conf.py it is referred as master_doc).

Then each file must be referenced, either in a toctree or a include, or a link, etc.

Look at examples on github (ie: the Sphinx-doc repository).

Fruit

I know about the index file and the toctree, etc. I use that in each manual. I am not talking about multiple .rst files to be linked into one manual, I am talking about multiple manuals, each with its own conf.py and directory structure, each started in their own directory with a sphinx-quickstart. They are standalone manuals that happen to live in the same repository. – Phalan

Sorry, i didn't understand it that way at all. Hum, the only time i did something remotely like your setup was with a main conf.py at the root which was used to configure all the manuals which where in subdirectories... i'm curious to learn about the solution which will appear in this thread. – Fruit