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.
- 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
.
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
.
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 https://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.
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.
- If you get an
extension error
or aconfiguration 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
.