Generating the documentation
============================

e-cidadania documentation is generated through sphinx (1.1.x) in three languages
by default, which are:

- English
- Spanish
- Galician

The current structure of the documentation is::

    docs/
        en/
        es/
        gl/
        reference/
        build/
        dev/ *
        docs/ *
        theming/ *
        index.rst *
        authors.rst *

The folders `en`, `es` and `gl` contain the documentation for each language.
The `reference` folder is the autogenerated documentation from the code
comments, which will always be in english and therefore is linked to all the
languages to have just one copy of the reference instead of updating three.

The same occurs to the last folders and files. For compatibility reasons we
left the "typical" structure of sphinx projects, although they are just
links to the english documentation. This trick allows us to publish the
documentation in places like *`Read The Docs <http://readthedocs.org>`_*

We divide the documentation into four big categories::

    dev/       -- Development or administration related (installation, configuration and deployment)
    docs/      -- Usual documentation: user manual, administrator manual, etc.
    theming/   -- Theming related tutorials, index of themes, etc.
    reference/ -- Reference documentation generated from the code comments.

The documentation is done to be the most automatic possible. The three
languages are generated at the same time when `make html` is executed.

Once that command is executed the documentation will be in the `build`
folder which is divided this way::

    build/
        doctrees/
        html/
            es/
            en/
            gl/
        latex/
            es/
            en/
            gl/

The folders `es`, `en` and `gl` contain the documentation for their
respective languages. The `doctrees` folder is just for reference when
generating the documents.

As you can see, there are two formats of documentation: `latex` and `html`.
e-cidadania has three officially supported formats for the documentation:
html, latex and PDF (generated through pdflatex and stored in the `latex`
directory).

.. note:: The way we designed the multilanguage system it should allow to
          build every format supported by sphinx (like epub, manpages,
          htmlhelp, etc.), but we don't guarantee it.

In the same way that you can build all the languages at once, you can also
build them separately, executing the same *make* command but inside the
language folder.

Linguistic rules
----------------

Not applicable to english translation at this time.

Fuzzy words
-----------

Not applicable.