Contribute to Existing Docs¶
To contribute to a repo that already has Sphinx/RtD set up, you will need to initiate a temporary virtual environment where you can build docs locally before pushing your changes.
After forking/cloning the repo normally, locate the
requirements.txt file in the project directory and navigate into that folder.
Create a virtual environment for the repo’s docs:
$ pipenv install -r requirements.txt
An error means a requirement is missing from your system or you are not in the correct directory.
A repo’s gemfile says what you need to install; the lockfile conveys the particular versions needed.
Activate the virtual environment:
$ pipenv shell
Build Docs Locally¶
Build the docs as static HTML files for editing:
$ pipenv run make html
The resulting information should indicate that the docs are ready in
Run this in the directory where the
Run this again after installing any missing requirements.
Run this when you want to view the docs (i.e., as a QA check before committing and opening a PR).
Run this whenever you need to rebuild docs (e.g., after un-staging a staged file).
pipenv runwhen building docs via a virtual environment (otherwise, it would just be
You can open a file in your browser to QA your changes:
$ open _build/html/Filename.html
Commit your edits and submit a PR normally.
When Finished Editing¶
You may want to update your
.gitignore file with any changes to system files that you do not want committed.
Exit the virtual environment before switching to another repo by pressing
ctrl-d. If you don’t do this, repo B will look at the requirements in repo A instead of finding its own.