forked from jaraco/skeleton
-
Notifications
You must be signed in to change notification settings - Fork 2
Read the Docs Setup
Pablo Prietz edited this page Mar 3, 2022
·
1 revision
The Python Module Skeleton is set up to use the following three technologies for its documentation:
-
reStructuredText (short rst) - plaintext markup language; files can be found in the
docs/
folder -
Sphinx - generates HTML from rst; configuration file is located at
docs/conf.py
-
Read the Docs (short RTD) - automating building, versioning, and hosting of the documentation;
configuration file is located at
.readthedocs.yml
Read the Docs can be configured to automatically
- Pull changes from Github
- Install this Python module
- Build the documentation using Sphinx
- Publish the HTML files at
your-project-url.readthedocs.io
- Go to https://readthedocs.org/dashboard/import/
- Select the repository and follow the setup instructions
RTD provides the possibility to host different versions (equivalent to commits) of your documentation. By default, there are two versions:
-
latest
- latest commit on themain
branch -
stable
- latest tag corresponding to a final release
To set up new versions, e.g. for a staging branch, go to https://readthedocs.org/projects/<project>/versions/
and select the tag or branch listed under Activate a version. In the next step, tick the corresponding check boxes:
-
Active
- Causes this tag/branch to be built as a new version -
Hidden
- If not selected the version won't be listed in the version selector, accessible at the bottom of every RTD website
The version is accessible via https://<project-name>.readthedocs.io/en/<version>/