Quickstart
Installation
Install the extension:
$ pip install sphinx-multiproject
Usage
You can structure your project like this:
docs
├── conf.py
├── dev
│ ├── conf.py
│ └── index.rst
└── user
├── conf.py
└── index.rst
Where docs/conf.py
would be your shared configuration file,
and docs/dev/
and docs/user/
would be your projects
using their specific configuration file.
# File: docs/conf.py
extensions = [
"multiproject",
# Your other extensions.
"sphinx.ext.intersphinx",
...
]
# Define the projects that will share this configuration file.
multiproject_projects = {
"user": {},
"dev": {
# Set a custom path.
"path": "dev",
},
}
# Common options.
html_theme = "sphinx_rtd_theme"
Then build your project as usual.
# Build the default project (user)
$ sphinx-build . _build/user/html
Or you can build each project by chaning the PROJECT
environment variable.
# Build the dev project
$ PROJECT=dev sphinx-build . _build/dev/html
Importing your projects on Read the Docs
Define your .readthedocs.yaml file as usual:
version: 2
build:
os: ubuntu-20.04
tools:
python: "3.9"
sphinx:
# Path to the shared conf.py file.
configuration: docs/conf.py
And on each project create an environment variable
called PROJECT
with the proper value of the project you want to build.