Skip to content

Latest commit

 

History

History
132 lines (91 loc) · 5.04 KB

UPDATING-THE-DOCS.md

File metadata and controls

132 lines (91 loc) · 5.04 KB
Raw

Guide to updating the Project X-Ray docs

We welcome updates to the Project X-Ray docs. The docs are published on Read the Docs and the source is on the docs branch on GitHub.

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 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 html generates output without errors
  • Check that make linkcheck reports no warnings.
  • When editing, make livehtml is helpful.

To make these checks work, you need to install Sphinx. We recommend pipenv.

Follow the steps below to install pipenv via pip, run pipenv install in the docs directory, then run pipenv shell to enter an environment where Sphinx and all the necessary plugins are installed:

Steps in detail, on Linux:

  1. Install pip:

     sudo apt install python-pip

  2. Install pipenv - see the pipenv installation guide:

     pip install pipenv

  3. Add pipenv to your path, as recommended in the pipenv installation guide. On Linux, add this in your ~/.profile file:

     export PATH=$PATH:~/.local/bin source ~/.profile

    Note: On OS X the path is different: ~/Library/Python/2.7/bin

  4. Go to the docs directory in the Project X-Ray repo:

     cd ~/github-repos/prjxray/docs

  5. Run pipenv to install the Sphinx environment:

     pipenv install

  6. Activate the shell:

     pipenv shell

  7. Run the HTML build checker, and check for errors:

     make html

  8. Run the link checker, and check for warnings:

     make linkcheck

  9. To leave the shell, type: exit.

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):

  1. Sign up for a RtD account here: https://readthedocs.org/

  2. 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.)

  3. Go to your RtD dashboard.

  4. Click Import a Project.

  5. 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, your-username-prjxray.

  6. 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.

  7. 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 master or trunk.

  8. RtD now builds your doc site, based on the contents in your Project X-Ray fork.

  9. 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.