Guide to updating the Project X-Ray docs
Updating the docs is a three-step process: Make your updates, test your updates, send a pull request.
1. Make your updates
The standard Project X-Ray contribution guidelines apply to doc updates too.
Follow your usual process for updating content on GitHub. See GitHub's guide to working with forks.
2. Test your updates
Before sending a pull request with your doc updates, you need to check the effects of your changes on the page you've updated and on the docs as a whole.
Check your markup
There are a few places on the web where you can view ReStructured Text rendered as HTML. For example: https://livesphinx.herokuapp.com/
Perform basic tests: make html and linkcheck
If your changes are quite simple, you can perform a few basic checks before sending a pull request. At minimum:
- Check that
make htmlgenerates output without errors
- Check that
make linkcheckreports no warnings.
- When editing,
make livehtmlis helpful.
To make these checks work, you need to install Sphinx. We recommend
Follow the steps below to install
pipenv install in
docs directory, then run
pipenv shell to enter an environment where
Sphinx and all the necessary plugins are installed:
Steps in detail, on Linux:
sudo apt install python-pip
Install pipenv - see the pipenv installation guide:
pip install pipenv
Add pipenv to your path, as recommended in the pipenv installation guide. On Linux, add this in your
export PATH=$PATH:~/.local/bin source ~/.profile
Note: On OS X the path is different:
Go to the docs directory in the Project X-Ray repo:
Run pipenv to install the Sphinx environment:
Activate the shell:
Run the HTML build checker, and check for errors:
Run the link checker, and check for warnings:
To leave the shell, type:
Perform more comprehensive testing on your own staging doc site
If your changes are more comprehensive, you should do a full test of your fork of the docs before sending a pull request to the Project X-Ray repo. You can test your fork by viewing the docs on your own copy of the Read the Docs build.
Follow these steps to create your own staging doc site on Read the Docs (RtD):
Sign up for a RtD account here: https://readthedocs.org/
Go to your RtD connected services, click Connect to GitHub, and connect RtD to your GitHub account. (If you decide not to do this, you'll need to import your project manually in the following steps.)
Go to your RtD dashboard.
Click Import a Project.
Add your GitHub fork of the Project X-Ray project. Give your doc site a name that distinguishes it from the canonical Project X-Ray docs. For example,
Make your doc site protected. See the RtD guide to privacy levels. Reason for protecting your doc site: If you leave your doc site public, it will appear in web searches. That may be confusing for readers who are looking for the canonical Project X-Ray docs.
Set RtD to build from your branch, rather than from master. This ensures that the content you see on your doc site reflect your latest updates:
- On your RtD dashboard, open your project, then go to Admin > Advanced Settings.
- Add the name of your branch in Default branch. This is the
branch that the "latest" build config points to. If you leave this field
empty, RtD uses
RtD now builds your doc site, based on the contents in your Project X-Ray fork.
See the RtD getting-started guide for more info.
3. Send a pull request
Follow your standard GitHub process to send a pull request to the Project X-Ray repo. See the GitHub guide to creating a pull request from a fork.