Getting started with the Ops Manual, reStructuredText, and Sphinx¶
The Ops Manual is maintained as a Sphinx project on GitHub. This means that the pages you’re viewing are plain text files (actually, they’re in a format called reStructuredText, of which more later) which live in a git repository. Editing the manual is as simple as clicking the “Edit on GitHub” link which appears in the sidebar of each page. When you click “Commit changes,” your changes will be built and pushed to the live copy of the manual that you’re looking at. It might take a minute or two before your changes are live.
Alternatively, if you’re more comfortable on the command line, you can check out the repository and work on the files on your own computer:
git clone email@example.com:okfn/opsmanual cd opsmanual vim opsmanual-getting-started.rst git commit -am "Improve the getting started guide" git push
You can also build the project locally by running
make html from the root of
the project. The built site will be placed in
_build/html. You don’t need to
do this, but if you’re making large edits it can help you preview your changes
Ops Manual Structure¶
The manual is divided into a few sections, each broadly aimed at a particular group in a particular role. Existing sections include:
- Guides to getting stuff done at the Open Knowledge Foundation. Most people will want to start here.
- Internal documentation and content aimed primarily at members of the OKF sysadmin team.
The tables of contents that form the main navigational structure of the site are
index.rst files at various points. See the
directives in, for example, index.rst or
2nd-line/index.rst. If you’re adding a new
page you should ensure it’s included in at least one
toctree so it’s
discoverable from the root of the site. (Although even if you don’t add it to a
ToC, it will still show up in the site search.)
The manual pages are written in a format called reStructuredText, or rST. At its simplest, rST is much like the Markdown format with which you may be more familiar. You can view the rST source of any page on this site by clicking the “Show Source” link in the left-hand column.
Some useful resources for getting started editing rST documents:
The content you push to GitHub constitutes the “source format” of the manual. This source content is compiled by Sphinx into the web pages you are currently viewing. This is done by a Travis CI job. The output of this job will also inform you of any rST syntax errors or other problems Sphinx encountered when building the site.
The build artefacts (a static HTML website) are copied into the
branch of the git repository and pushed to GitHub. The manual is then served at: