Documentation#

Guide for contributing to Construbot documentation.

Overview#

Construbot documentation uses Sphinx with reStructuredText (RST) and supports bilingual builds (English/Spanish).

Location: /docs/

Building Documentation#

Build English docs:

cd docs
make html
open _build/html/index.html

Build Spanish docs:

make html-es
open _build/html/es/index.html

Auto-rebuild (live preview):

make livehtml
# Opens http://127.0.0.1:8000

Writing Documentation#

RST Syntax:

==============
Page Title
==============

Section
=======

Subsection
----------

**Bold text**
*Italic text*
``Code inline``

.. code-block:: python

   # Code block
   def example():
       pass

.. note::
   Admonition block

Links:

:doc:`other-page`
:doc:`/full/path/to/page`
`External link <https://example.com>`_

Cross-references:

See :doc:`../architecture/overview`
See :class:`construbot.proyectos.models.Contrato`

Documentation Structure#

docs/
├── index.rst (main entry point)
├── user-guide/
├── developer/
├── contributor/
├── reference/
└── _glossary/

Follow existing structure when adding new pages.

Style Guide#

1. Clear and concise

2. Code examples

Include working code examples.

3. Spanish terms

Use pattern: “Contracts (Spanish: Contratos)”

4. Cross-references

Link to related pages.

5. Consistent formatting

Follow existing page structure.

Translation Workflow#

Extract strings:

cd docs
make gettext

Update translations:

make update-translations

Edit .po files:

# Edit locale/es/LC_MESSAGES/*.po
nano locale/es/LC_MESSAGES/index.po

Build Spanish version:

make html-es