KoboToolbox user documentation

This repository contains all the user content of KoboToolbox's official documentation, available at https://support.kobotoolbox.org/.

Before you open an issue…

Please note that the purpose of the issue tracker on this repository is to track work on the technical infrastructure of the documentation site. For requests related to the content of the documentation, please:

• Post in Zulip #Kobo support docs if you are a member of the Kobo team
• Otherwise, please share your feedback through our Community Feedback Form
• For support requests or bug reports, please post in the Community Forum

Local installation

To build and test this documentation locally follow these steps:

Prerequisites:

• Python 3.10 or later (Python 3.13+ supported)
• git
• npm

1. Open terminal
2. Clone repository: git clone https://github.com/kobotoolbox/docs.git
3. Change into the cloned directory: cd docs
4. Build the theme if you made any changes to it: npm install && npm start
5. Create a virtual environment: python -m venv koboenv
6. Activate the virtual environment source koboenv/bin/activate
7. Install requirements pip install -r requirements.txt
8. Build the html files: make html
9. Open the index page in the browser: open _build/html/index.html

Note: if you have Python 3, you might need to use python3 command instead of python (and pip3 instead of pip).

Each commit to master is automatically built into production.

Development

When you already did everything from "Local installation" succesfully and just need to come back and work a bit more on the project, please use dev.sh script from the root of the project.

Internationalization

The documentation supports multiple languages. The structure is:

• source/ - English content (default language)
• locales/es/ - Spanish translations
• locales/fr/ - French translations
• locales/ar/ - Arabic translations

Building translated documentation

To build documentation in a specific language:

# Build English (default)
make html

# Build Spanish
sphinx-build -b html locales/es _build/html/es

# Build French
sphinx-build -b html locales/fr _build/html/fr

# Build Arabic
sphinx-build -b html locales/ar _build/html/ar

Adding new translations

1. Create the translated file in locales/[lang]/ with the same filename as the English version (e.g., locales/es/new_article.md)
2. Add the file to the corresponding locales/[lang]/index.rst toctree
3. Add language switcher links at the top of each version (Language switcher links have been removed)

Custom theme development

We build our theme atop Read The Docs theme by replacing their CSS with our own (which is a heavily modified copy of theirs).

To develop the theme:

1. Install NPM dependencies: npm install
2. Build:
3. To watch for style changes use npm run dev
4. To build the styles once use npm start

Useful links:

• Jinja - templating language used in .html files
• Official Sphinx documentation
• Alabaster theme source code
• Sphinx source code
• Basic Sphinx theme source code