ODK Docs

This repo is the source for ODK documentation.

The published documentation is at:

• https://docs.opendatakit.org
• https://docs.opendatakit.org/odk2/

If you can't find what you are looking for, try the old docs on the ODK website. Also, please file an issue so that we know to add the information you are looking for.

Building and viewing documentation locally

The following steps help you build and view ODK docs locally. For details on each of these steps, see the Contributor Guide.

Prerequisites

• Install Python 3.
• Install Git-LFS.

We highly recommend you use a virtual environment like virtualenv or a Python version management like pyenv. (Type python --version to see your current version.)

Cloning the repo

After that, you need to clone the docs repo and make sure all the requirements are installed:

$ git clone https://github.com/opendatakit/docs.git
$ cd docs/
$ 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 odk1
$ cd odk1-build
$ python -m http.server 8000

You can then view the docs in your browser at http://localhost:8000.

(Use odk2 instead of odk1 to build and serve the ODK2 docs.)

You can also use make to build both ODK and ODK2 docs, or to run just a portion of the build process.

For both ODK 1 and ODK 2:

	Build	Clean	Check Style & Spell
Options	build-all	clean	check-all

For a specific ODK version:

	Copy	LaTeX	Style Check	Spell Check	Check All
Options	odk1-copy	odk1-latex	odk1-style-check	odk1-spell-check	odk1-check

To build ODK 2 docs, just replace odk1 with odk2.

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.x).
  • Run pip install -r requirements.txt.