monicaiyb/docs

The documentation for all the ODK tools. This is one of the most popular artifacts our community produces. It's built in Sphinx. ✨📚✨

ODK Docs

This repo is the source for ODK documentation.

The published documentation is at:

• https://docs.getodk.org

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

Building and viewing documentation

Prerequisites

• Install Python 3
• Install git
• Install Git-LFS

We highly recommend you use a virtual environment like virtualenv.

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