ManualStandards: Difference between revisions
(adding basic manual standards doc) |
(adding notes about sphinx) |
||
Line 1: | Line 1: | ||
= Manual Standards = |
= Manual Standards = |
||
We use [http://sphinx.pocoo.org/ Sphinx] to build the user manual. It's located in the <tt>docs/</tt> directory of the repository. |
|||
FIXME - lots of stuff to add here regarding conventions, ... |
FIXME - lots of stuff to add here regarding conventions, ... |
||
Line 16: | Line 18: | ||
== Texinfo == |
== 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 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: |
|||
Run: |
|||
cd docs/ |
cd docs/ |
Revision as of 22:37, 30 July 2011
Manual Standards
We use Sphinx to build the user manual. It's located in the docs/ directory of the repository.
FIXME - lots of stuff to add here regarding conventions, ...
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.