Open Data Kit Documentation, built in Sphinx.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci Use manual xelatex commands to reduce dependencies on latex container Aug 4, 2018
.github Make text easier to read Apr 10, 2018
_sources smaller logo, with 'documentation' Aug 23, 2017
odk1-config
odk1-src
odk2-config Prepare for multi bucket deployment Mar 21, 2018
odk2-src
shared-config Remove quotes in circleci config + remove latex exclude from shared-docs Mar 21, 2018
shared-src Add section about Briefcase log files and configuration (#898) Oct 24, 2018
style-guide
tests
util
.gitattributes include gimp .xcf in gitattributes Aug 23, 2017
.gitignore
Dockerfile Add sphinx-autobuild to the tools Sep 27, 2018
LICENSE.md
Makefile Improve README with Docker instructions Oct 5, 2018
README.md Add build and serve command back Oct 9, 2018
make.bat
requirements.txt Fix for CVE-2018-18074 (#904) Oct 30, 2018
run-task.bat Add simple scripts to launch Makefile tasks with the Docker container Oct 5, 2018
run-task.sh Add simple scripts to launch Makefile tasks with the Docker container Oct 5, 2018
ss.py
style-test.py Added source path to style check list generator Mar 12, 2018
style-test.txt Literate programming (#515) Feb 27, 2018
video.py

README.md

ODK Docs

Platform License Build status Slack status

This repo is the source for ODK documentation.

The published documentation is at:

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

Building and viewing documentation locally

There are two options for building and viewing ODK docs locally: using Docker or setting up a local Python/Sphinx environment. We generally recommend starting with the Docker image unless you already have a Sphinx environment set up. The Contributor Guide describes the philosophy behind the docs, style considerations, how to write restructured text and more.

Using Docker

Docker is a platform that makes it easier to package applications so that they can work on any computer. This is particularly valuable when setting up development environments which can work very differently based on versions of the tools involved.

Prerequisites

Cloning the repo

Clone the docs repo. For example, at the command line:

git clone https://github.com/opendatakit/docs.git

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 Docker image

Next, you need to build the Docker image with all the tools you will be using to work with ODK's docs.

docker build -t odk-docs .

It can take a long time to build the Docker image, but you only need to do this once.

Windows users

  • All commands should be run in an elevated PowerShell window. Right click on PowerShell and select the "Run as administrator" option.
  • Ensure Docker is running by checking your system tray. If Docker is not running, launch "Docker for Windows" app and wait until a notification confirms that Docker is running.

Building and serving the docs locally

Build and serve the docs locally with:

  • Windows: .\run-task.bat odk1-autobuild
  • Linux/macOS: ./run-task.sh odk1-autobuild

Once your terminal shows a "Serving on http://0.0.0.0:8080" message, you can then view the docs in your browser at http://localhost:8080.

Changes you make in the source files will automatically be built and shown in your browser.

Press Ctrl-C on your keyboard to stop the build server. It could take a while to effectively stop, and you can always close the terminal window.

If you get a The name "odk-docs" is already in use by container error message, run the following command:

docker kill odk-docs

Other build tasks

You can also use the run-task script described above to build both ODK 1 and ODK 2 docs, or to run just a portion of the build process. See available build tasks below.

Python environment

Prerequisites

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

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. See available build tasks below.

Build tasks

For both ODK 1 and ODK 2:

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

For a specific ODK version:

Build & Serve Build Copy LaTeX Style Check Spell Check Check All
Options odk1-autobuild odk1-build 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...

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.