README.md

KoboToolbox user documentation

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

Local installation

To build and test this documentation locally follow these steps:

Prerequisites:

• Python 3
• 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.

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