ODK-X Docs

This repo is the source for ODK-X documentation.

The published documentation is at:

• https://docs.odk-x.org/

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-X 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.

There are two options to build ODK-X documents

• Docker Hosted Build Environment
• Python Build Environment

The Docker environment is recommended because of the fewer setup steps required and less environmental variable paths that need to be set.

---

Using Docker Hosted Build Environment

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 that can work very differently based on versions of the tools involved.

Prerequisites

• Install Docker

  • Windows and Mac users should follow the instructions in the get started guide

    • An important requirement, is to make sure you have turned on hard ware Virtualization in the BIOS-level, this is necessary for Docker to run. For more information, see Virtualization.

      If you are unsure if Virtualization is enabled, you can easy check in the Windows Task Manager, Under the Performance tab, under CPU and where it says Virtualization : it can either show Enabled or Disabled

      Turning on Virtualization is vendor specific and you may have to find the right procedures for your computer

  • Linux users should follow the instructions for their specific distribution: CentOS, Debian, Fedora, Ubuntu, Binaries

  More info at the Docker CE docs page

• Install git

• Install Git-LFS

Forking the repo

Fork the odk-x/docs repository, so that a copy of odk-x/docs gets created in your github account.

Cloning the repo for contribution

Clone the docs repo into a directory you want the ODK-X docs files to be located. Below are the steps required to clone the docs repo:

1. Visit this link https://github.com/odk-x/docs on your browser to locate the docs repo
2. Find and click the "fork" button to create a personal fork of the project on Github
3. Navigate to the directory you want the files to be located using the "cd" (Change Directory) command on a command-line interface on your local machine:

cd <DIRECTORY>

4. Get a copy of the ODK-X docs repository on your local machine by cloning the forked repo to your local machine from your github account using the clone command below. Replace "LINK-TO-YOUR-FORKED-REPO" below with the actual link to your forked repo: You need to click on the green "Code" button to get the "LINK-TO-YOUR-FORKED-REPO"

git clone <LINK-TO-YOUR-FORKED-REPO>

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.

After the git clone finishes, use the below command to change the directory to the ODK-X docs directory

cd docs

Building the Docker image

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

docker build -t odkx-docs .

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

Take note of the full-stop . at the end of the build command. The . specifies the build context, which is the path to the directory containing the Dockerfile and any other files needed to build the image and -t odkx-docs specifies the name and optionally a tag for the image that is getting build (odkx-docs in our case).

Windows users

• All commands should be run in an elevated PowerShell window. Right-click on PowerShell and select the "Run as administrator" option. NOTE: when running as an administrator PowerShell will default to the Windows directory. You will need to use the "cd" (Change Directory) command to navigate to a directory that you want the ODK-X documentation files to be located.
  • 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.
  • Once the build is done, you should now see the odkx-docs image under images in Docker Desktop

Building and serving the docs locally

Build and serve the docs locally with:

• Windows: .\run-task.ps1
• Linux/macOS: ./run-task.sh

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 (located in the ./src folder) will automatically be re-built and shown in your browser.

• Windows: The docker container with the docs website will occupy the terminal window and output log messages when changes are detected and rebuilds are made. Open a new terminal window/tab to be able to stop the container using the command below.
• Linux/macOs: Open a new terminal to interact with the container or press Ctrl-Z on your keyboard to suspend the job. The job will still be running in the background and changes will automatically be rebuilt and served.

To stop the container, type the following command

docker stop odkx-docs

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

docker kill odkx-docs

Other build tasks

You can also use the run-task script described above to run just a portion of the build process. See available build tasks below.

---

Python Environment

Prerequisites

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

After installing, you should verify that Python was successfully installed and is available on your PATH. To verify Python is installed properly and has been added to your PATH, query the Python version using the following command.

Bash (Linux/Mac)

$ python3 --version

PowerShell (Windows)

> python --version

The system should return something like "Python 3.X.X" where X is the other version numbers of your install.

Here is a website that explains how to set up Python to be on the Window's PATH.

(Optional) Setup Python Virtual Environment

We recommend you use a virtual environment like virtualenv or a Python version management like pyenv to avoid conflicts with packages. This section can be skipped if you do not have multiple Python projects using pip (package installer for Python).

• Instructions for setting up virtual environment:

  A `virtual environment`_ is a Python construct
  that lets you download and install tools for a specific project
  without installing them for your entire computer.
  
  .. _virtual environment: https://docs.python.org/3/tutorial/venv.html
  
  #. Create a directory called 'odkx'
      Create a directory for the documents. We will use the folder 'odkx' as the directory that will contain the ODK-X Docs environment.
  
  
    	mkdir odkx
  
  
      Next, change the current working directory to 'odkx'
  
  
    	cd odkx
  
  
  #. Create the virtual environment.
  
  
  
    Next, create the virtual environment.
  
    	Bash
  
    		/odkx/ $ python3 -m venv odkxenv
  
        PowerShell
  
            /odkx/ > python -m venv odkxenv
  
  #. Activate the virtual environment.
  
    	Bash
  
            /odkx/ $ source odkxenv/bin/activate
            (odkxenv) /odkx/ $
  
    	PowerShell
  
            /odkx/ > .\odkxenv\Scripts\activate
            (odkxenv) /odkx/ >
  
     The ``(odkxenv)`` before the prompt shows that the virtual environment is active.
     You will need to have this active any time you are working on the docs.
  
     If the file cannot be found, your activate file may be located under odkxenv/scripts/activate.
  
     Later, to deactivate the virtual environment:
  
      Bash
  
              (odkxenv) /odkx/ $ deactivate
              /odkx/ $
  
      PowerShell
  
              (odkxenv) /odkx/ > deactivate
              /odkx/ >
  

Cloning the repo

Clone the docs repo and make sure all the requirements are installed:

$ git clone https://github.com/odk-x/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 serve

$ make odkx
$ cd build
$ python -m http.server 8000

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

You can also use make to run just a portion of the build process. See available build tasks below.

Build tasks

	Build & Serve	Build	LaTeX	PDF	Spell Check
Options	serve	dirhtml	latex	latexpdf	spelling

To run a style check, you can issue the following python command:

python3 style-test.py $(git diff origin/main --name-only) -r src

How to contribute?

We are open to new issues and pull requests.

• Please read the Contributors Guide before working on the documentation.
• Find issues to work on.
  • Issues labeled easy win do not require much specific technical knowledge.
  • Issues labeled good first issue are usually self-contained and don't require extensive knowledge of the ODK-X ecosystem as a whole.

You can also...

• Discuss the documentation from a user perspective in our forum.
• 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.