wrappedcoder/docs

Open Data Kit Documentation, built in Sphinx.

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

See the Contributor Guide for detailed steps --- no prior experience needed!

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

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

$ git clone https://github.com/opendatakit/docs.git
$ cd docs/
$ pip install -r requirements.txt

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.