ODK Docs

The source for ODK documentation published at https://docs.getodk.org.

Please file an issue if you can't find what you are looking for.

[!NOTE] The source for the Central API documentation is managed in the Central code repository and copied here as part of the Central release process.

Building and viewing documentation

Prerequisites

• Install Python 3.10+
• Install git
• Install Git-LFS
• Install Enchant.

We highly recommend you use a virtual environment like virtualenv. If you need to use different versions of Python, we recommend pyenv.

Cloning the repo

Clone the docs repo and make sure all the requirements are installed:

$ git clone https://github.com/getodk/docs.git
$ cd docs/

If you wish to use virtualenv, now is a good time to set it up:

$ python -m venv venv
$ source venv/bin/activate

You will see (venv) next to your prompt to indicate you are working within the docs project. To exit this mode, use the command deactivate.

Whether you are using virtualenv or not, you next need to install the dependencies:

$ pip install -r requirements.txt

It can take a long time (>10 minutes) to clone the repo due to the large number of images in the docs. If you get an error such as Smudge error or GitHub's rate limit reached, run git checkout -f HEAD until you get the message Checking out files: 100% done.

Building the docs

Once your environment is set up, build and serve the docs locally with:

$ make autobuild

You can then view the docs in your browser at http://localhost:8000. The docs will auto-build and refresh as you make changes to the source files.

You can use make dirhtml to for a one-time build of the HTML files and make clean to clean the build.

How to contribute?

We are open for new issues and pull requests.

• Please read the Contributors Guide before working on the documentation.
• Find issues to work on.
  • First time contributors are encouraged to complete a line edit as a way to get familiar with our contribution process.
  • Issues labelled easy do not require much specific technical knowledge.
  • Issues labelled contributor friendly are usually self-contained and don't require extensive knowledge of the ODK ecosystem as a whole.

You can also...

• Discuss the documentation from a user perspective in our forum.
• Discuss the documentation from a contributor perspective in our developer Slack. (Use the #docs-code channel.)
• File an issue for any needed improvements.
• Watch and star this repo, to keep up with what we're doing.

Troubleshooting

• If you get an extension error or a configuration error:
  • Make sure your virtual environment is activated.
  • Type python --version to check your current python version (it should be 3.10+).
  • Run pip install -r requirements.txt.