Write documentation

We believe Raspberry IO needs to have documentation as good as our code. It’s what you’re reading now and is generally the first point of contact for new developers. We value great, well-written documentation and aim to improve it as often as possible. And we’re always looking for help with documentation!

Getting the raw documentation

The official documentation is available on Read the Docs. This is the compiled HTML version. However, we edit it as a collection of text files (reST format) which live in the top-level docs/ directory of a Raspberry IO release. Note that the official documentation is currently built from the develop branch.

Using Sphinx

Before building the documentation, you must have downloaded the Raspberry IO source code. See the Get the code section for instructions on installing Raspberry IO locally.

We use the Sphinx documentation system (based on docutils). To build the documentation locally, you’ll need to install Sphinx.

$ pip install Sphinx

Then, building the HTML is easy. Just run make from the docs directory.

$ cd raspberryio/docs
$ make html

(or make.bat html on Windows)

The compiled HTML code will be in raspberryio/docs/_build/.

To get started contributing, you’ll want to read the reStructuredText Primer. After that, you’ll want to read about the Sphinx-specific markup that’s used to manage metadata, indexing, and cross-references.

Documentation starting points

Typically, documentation changes come in two forms:

• General improvements: typo corrections, error fixes and better explanations through clearer writing and more examples.
• New features: documentation of features that have been added to the framework since the last release.

If you’re interested in helping out, a good starting point is with the documentation label on the GitHub issue tracker.