ManualStandards

Overview

We use Sphinx to build the user manual. It's located in the docs/ directory of the repository.

Conventions

Style

The manual has three parts to it that cater to three different target audiences:

Site Administrator's Guide

Written for people who want to install MediaGoblin on their server and maintain it. This is an outward-facing part of our project, so the tone needs to be upbeat, exciting at times, and inclusive. The site administrators are becoming part of our community when they choose to use MediaGoblin. The documentation tone should reflect that. This isn't just a piece of software, it's a revolution! Having said that, the tone shouldn't adversely affect clarity--the documentation needs to be clear.

Core Plugin Documentation

This documentation is located in README files in the core plugin directories. It needs to be clear, easy to read, easy to follow sets of instructions for installation, upgrading, configuring and using the respective plugins.

Plugin Writer's Guide

Written for people who are writing plugins. This documentation can be on the technical side of things. Like the Site Administrator's Guide, it's an outward-facing part of our project and so it should be upbeat and inclusive. It is technical documentation, though, so lists, definition lists, and other technical shorthand is important. Working examples are important.

Heading hierarchy

We use the following heading hierarchy:

   ================
    Document title
   ================
   
   Heading 1
   =========
   
   Heading 2
   ---------
   
   Heading 3
   ^^^^^^^^^

FIXME - more style examples needed

Building output

HTML

To build, do:

   cd docs/
   make html

The HTML version of the docs will then be in docs/_build/html/.

Texinfo

To build, you need to use the latest tip from Sphinx in hg to build the manual into a Texinfo file. The texinfo builder/writer haven't been released in a final Sphinx release, yet. To get a copy, you need to do an hg clone:

   hg clone https://bitbucket.org/birkenfeld/sphinx

You need to install it. I install it in a virtual environment:

   mkvirtualenv sphinxtip
   cd sphinx/
   python setup.py develop

After you have a copy of the latest Sphinx in hg installed, run:

   cd docs/
   make info

The Texinfo version of the docs will then be in docs/_build/texinfo/.

To test, open up Emacs and do C-u C-h i and then select the .info file. Read through it, make sure the images are correct and that there aren't weird things. Note that you need to use a graphical Emacs and not a command shell Emacs.