SlipStream Documentation Sources
This repository contains the sources for all of the SlipStream documentation. If you are looking for the documentation itself, visit the documentation website instead.
To update or add documentation:
- Clone this repository.
- Checkout the
- Edit or add source files in the
docssubdirectory, organizing them hierarchically.
- Test the changes by running Sphinx locally and viewing the result.
- Commit the changes to the repository and ask people to review your changes.
- After review, merge the changes into the
The following sections describe each of these steps in more detail.
Pushing changes to the
master branches trigger
webhooks that make those versions visible on the ReadTheDocs site.
All of the sources are contained in this git repository on GitHub. To checkout the sources:
$ git clone [email protected]:slipstream/SlipStreamDocumentation.git
If you don't have write access to this repository, then use one of the read-only URLs for it.
draft branch for your changes.
$ git checkout draft
Push the changes to GitHub when you want to see the rendered draft material on the ReadTheDocs site.
All of the source documentation is written in reStructured Text format.
Simply update the documentation files in the
When updating or adding sources, please:
- Ensure the files remain as plain text in US-ASCII encoding.
- Use Unix line endings (and not Windows).
- Use spaces and not tabs.
- Wrap lines at column 72 and flow text.
Using a consistent style in text format makes it easier to maintain the documentation.
To test your changes to the documentation, you should run Sphinx locally.
Good instructions for installing the necessary dependencies can be found on the Sphinx documentation website and on the ReadTheDocs stylesheet README. This essentially comes down to the
$ pip install Sphinx sphinx-autobuild sphinx-rtd-theme
You will also need to have the
make command installed for unix-like
machines, or use the
make.bat script on Windows.
From the root of the repository just run:
$ make clean; make html
The generated HTML documentation will be in
build/html with the root
This is a standard git repository, so committing the changes means just following the standard git workflow. Push your branch to the GitHub repository.
The changes will be published on the ReadTheDocs site automatically
when changes to the
master branches are pushed. It may
take a couple of minutes for the build process to run on the