Standards Lab: an open data standard toolkit

Visit https://os4d.opendataservices.coop to read the handbook.

Developer how-to guides

This section describes how to:

• Use dev containers or GitHub Codespaces for development
• Set up a local development environment
• Build the documentation on your local machine.
• Deploy changes
• Update requirements

Use dev containers or GitHub CodeSpaces for development

If your editor supports dev containers, you can open the project in a dev container. For example, if you're using VS Code, follow the installation instructions and the quick start guide to open a folder in a container.

You can also open the project in GitHub Codespaces.

Once connected to the container, open a new terminal and run the commands in Build the documentation.

When you have finished, make sure to delete your codespace on https://github.com/codespaces.

Set up a local development environment

Clone the repository

git clone git@github.com:OpenDataServices/os4d.git
cd os4d

Subsequent instructions assume that your current working directory is os4d, unless otherwise stated.

Create and activate a Python 3.13 virtual environment

The build requires Python 3.13. We recommend using pyenv to install and switch between multiple versions of Python.

1. Install pyenv

2. Install Python 3.13:

   pyenv install 3.13

3. Switch to Python 3.13:

   pyenv shell 3.13

4. Create a virtual environment using python3-venv:

   a. Linux/MacOS:

   python3 -m venv .ve

   a. Windows:

   py -m venv .ve

5. Activate the virtual environment. You must run this command for each new terminal session:

   a. Linux/MacOS:

   source .ve/bin/activate

   b. Windows:

   .\.ve\Scripts\activate

Install requirements

pip install -r requirements_dev.txt

Build the documentation

Sphinx, which builds the documentation, doesn’t watch directories for changes. To regenerate the documentation, start an HTML server, and refresh the browser whenever changes are made, run:

sphinx-autobuild docs docs/_build/dirhtml

Alternatively, build the documentation and view it using a local web server:

sphinx-build docs docs/_build/dirhtml
python -m http.server --directory docs/_build/dirhtml

Deploy changes

To deploy a development branch to the live documentation site, create a pull request to merge the development branch into the live branch. Once the pull request is merged, the changes are automatically deployed to the live site at https://os4d.opendataservices.coop/.

Update requirements

Update production requirements

1. Edit requirements.in.
2. Update requirements.txt:

   pip-compile

3. Update requirements_dev.txt:

   pip-compile requirements_dev.in

4. Install requirements:

   pip-sync requirements_dev.txt

5. Commit your changes.

Update development requirements

1. Edit requirements_dev.in.
2. Update requirements_dev.txt:

   pip-compile requirements_dev.in

3. Install requirements:

   pip-sync requirements_dev.txt

4. Commit your changes.

Developer reference

This section contains reference documentation that describes the project's configuration.

• GitHub repository
• Sphinx
• Read the Docs

GitHub repository

The project repository is hosted on GitHub.

Branches

The live branch is used to build the live version of the standard documentation, deployed at https://os4d.opendataservices.coop/.

Feature branches branch off the live branch, with work merged into the live for deployment.

Branch protection rules are configured for the live branch. The rules prevent commits being made directly by requiring pull requests before commits can be merged. They also require approvals and status checks to pass before merging.

Directory structure

• .github/: GitHub Actions workflows
• docs/:
  • *.md, */*.md: English documentation text
  • conf.py: Sphinx configuration
  • _static/: CSS and JavaScript for the documentation
  • _templates/: Jinja templates for the documentation
  • .tx/: Transifex configuration (not yet implemented)
  • locale/: Translations of the English documentation (not yet implemented)

The following files are created by running a build and are not version controlled:

• .ve/: Python virtual environment (if using python3-venv)
• docs/_build: Built HTML documentation

Sphinx

Sphinx is the documentation generator used to build the HTML documentation from Markdown source files. It uses the MyST - Markedly Structured Text - Parser to parse the Markdown source files.

Configuration

The Sphinx configuration for this project is based on the Open Data Services Sphinx Base and is defined in docs/conf.py.

Read the Docs

Read the Docs builds and hosts the standard documentation site.

Read the Docs automatically creates and builds pull request previews so that pull request reviewers can preview changes to catch formatting and display issues.

Credentials

You can find credentials for Read the Docs in the Open Data Services password database.