Guide to updating the Project X-Ray docs¶
The reason for using the
docs branch is to avoid running the full CI test suite which triggers when merging anything to
master. Ultimately of course the
docs branch needs to be synchronized with
master, but this can be done in bulk.
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 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
- 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
docs. 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.