See the Sphinx and Read the Docs guide for instructions on how to get started with Sphinx documentation.
Then go through the following sections to use this starter pack to set up your docs repository.
You can either create a standalone documentation project based on this repository or include the files from this repository in a dedicated documentation folder in an existing code repository.
Note: We're planning to provide the contents of this repository as an installable package in the future, but currently, you need to copy and update the required files manually.
To create a standalone documentation repository, clone this starter pack repository, update the configuration, and then commit all files to the documentation repository.
You don't need to move any files, and you don't need to do any special configuration on Read the Docs.
Here is one way to do this for newly-created fictional docs repository
canonical/alpha-docs
:
git clone git@github.com:canonical/sphinx-docs-starter-pack alpha-docs
cd alpha-docs
rm -rf .git
git init
git branch -m main
UPDATE THE CONFIGURATION
git add -A
git commit -m "Import sphinx-docs-starter-pack"
git remote add upstream git@github.com:canonical/alpha-docs
git push -f upstream main
To add documentation to an existing code repository:
- create a directory called
docs
at the root of the code repository - populate the above directory with the contents of the starter pack
repository (with the exception of the
.git
directory) - copy the file(s) located in the
docs/.github/workflows
directory into the code repository's.github/workflows
directory - in the above workflow file(s), set the values of the
working-directory
andworkdir
fields todocs
- in file
docs/.readthedocs.yaml
set the following:configuration: docs/conf.py
requirements: docs/.sphinx/requirements.txt
Note
When configuring RTD itself for your project, the setting Path for .readthedocs.yaml (under Advanced Settings) will need to be given the value of "docs/.readthedocs.yaml".
There are make targets defined in the Makefile
that do various things. To
get started, we will:
- install prerequisite software
- view the documentation
To install the prerequisites:
make install
This will create a virtual environment (.sphinx/venv
) and install
dependency software (.sphinx/requirements.txt
) within it.
A complete set of pinned, known-working dependencies is included in
.sphinx/pinned-requirements.txt
.
To view the documentation:
make run
This will do several things:
- activate the virtual environment
- build the documentation
- serve the documentation on 127.0.0.1:8000
- rebuild the documentation each time a file is saved
- send a reload page signal to the browser when the documentation is rebuilt
The run
target is therefore very convenient when preparing to submit a
change to the documentation. For a more manual approach, to strictly build and
serve content, explore the html
and serve
make targets, respectively.
You must modify some of the default configuration to suit your project.
To simplify keeping your documentation in sync with the starter pack, all custom configuration is located in the custom_conf.py
file.
You should never modify the common conf.py
file.
Go through all settings in the Project information
section of the custom_conf.py
file and update them for your project.
See the following sections for further customisation.
By default, the header contains your product tag, product name (taken from the project
setting in the custom_conf.py
file), a link to your product page, and a drop-down menu for "More resources" that contains links to Discourse and GitHub.
You can change any of those links or add further links to the "More resources" drop-down by editing the .sphinx/_templates/header.html
file.
For example, you might want to add links to announcements, tutorials, getting started guides, or videos that are not part of the documentation.
If your documentation uses US English instead of UK English, change this in the
.sphinx/spellingcheck.yaml
file.
To add exceptions for words the spelling check marks as wrong even though they are correct, edit the .wordlist.txt
file.
If you have links in the documentation that you don't want to be checked (for
example, because they are local links or give random errors even though they
work), you can add them to the linkcheck_ignore
variable in the custom_conf.py
file.
A feedback button is included by default, which appears at the top of each page in the documentation. It redirects users to your GitHub issues page, and populates an issue for them with details of the page they were on when they clicked the button.
If your project does not use GitHub issues, set the github_issues
variable
in the custom_conf.py
file to an empty value to disable both the feedback button
and the issue link in the footer.
If you want to deactivate only the feedback button, but keep the link in the
footer, set disable_feedback_button
in the custom_conf.py
file to True
.
You can add redirects to make sure existing links and bookmarks continue working when you move files around.
To do so, specify the old and new paths in the redirects
setting of the custom_conf.py
file.
To add custom configurations for your project, see the Additions to default configuration
and Additional configuration
sections in the custom_conf.py
file.
These can be used to extend or override the common configuration, or to define additional configuration that is not covered by the common conf.py
file.
See the change log for a list of relevant changes to the starter pack.