Generating the documentation

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

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.