We use Sphinx to build the user manual. It's located in the docs/ directory of the repository.
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.
We use the following heading hierarchy:
================ Document title ================ Heading 1 ========= Heading 2 --------- Heading 3 ^^^^^^^^^
FIXME - more style examples needed
To build, do:
cd docs/ make html
The HTML version of the docs will then be in docs/_build/html/.
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:
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.