ManualStandards

From GNU MediaGoblin Wiki
(Difference between revisions)
Jump to: navigation, search
(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
  
Run:
+
After you have a copy of the latest Sphinx in hg installed, run:
  
 
     cd docs/
 
     cd docs/

Revision as of 17: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.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox