Reference

This section contains the following reference documentation:

• GitHub repository
• Sphinx
• Read the Docs
• manage.py

GitHub repository

The project repository is hosted on GitHub.

Branches

The main branch is used to build the 'live' version of the standard documentation.

The dev branch is used to stage changes to the main branch.

Feature branches branch off the dev branch, with work merged into the dev branch before finally being merged into the main branch.

Branch protection rules are configured for the main and dev branches. 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/: Issue templates and 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)
  • img/: Images used in the documentation
  • locale/: Translations of the English documentation (not yet implemented)
• examples: Example JSON files, CSV files and figures
• schema/: schema- and codelist-related files
• specs/: TBD
• SteeringCommittee/: Minutes of steering committee meetings

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

• .ve/: Python virtual environment (if using python3-venv)
• docs/_readthedocs: 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. As part of the documentation build process, conf.py processes the schema and codelists for inclusion in the published documentation:

Schema processing

The source schema is structured according to the principle of "Don't repeat yourself" (DRY). In practice, this means use of reusable subschemas (the $defs keyword), pointers (the $ref keyword) and inheritance (the allOf keyword).

Adhering to the DRY principle eases maintenance through avoiding repetition of information that is likely to change and minimising the length of the schema. However, the resulting schema might be difficult for end users to follow, and some features are not fully supported by elements of the tech stack.

Therefore, during the build process (defined in docs/conf.py), the source schema is processed to produce the following schema files in docs/_readthedocs/html:

• rdls_schema.json - a copy of the schema/rdls_schema.json with the following changes:
  • $defs/conditional_hazard_type_to_process populated with conditional validation logic according to the hazard type / process mapping documented in process_type.csv
  • $defs/conditional_hazard_type_to_intensity_measure populated with conditional validation logic according to the hazard type / intensity measure mapping documented in imt.csv
• rdls_schema_processed.json - the above file with the following additional changes:
  • References to definitions in the schema are dereferenced according to the JSON Schema 2020-12 specification
  • Inherited schemas defined under the allOf keyword are merged with the parent schema.
• rdls_schema_processed_browser.json - the above file with the following additional changes:
  • Any remaining allOf and anyOf keywords, typically used to implement either/or validation of required fields, are removed for compatibility with the schema browser.

In all cases, {{version}} placeholders are replaced with the current branch name / version number.

Codelist processing

conf.py outputs the following codelist files in docs/_readthedocs/html/codelists:

• Individual process_type_<hazard_type>.csv codelists for each hazard type, e.g. process_type_earthquake.csv
• Individual imt_<hazard_type>.csv codelists for each hazard type, e.g. imt_earthquake.csv

Read the Docs

Read the Docs builds and hosts the standard documentation site.

Whenever a commit is pushed to a branch in the GitHub repository, Read the Docs automatically builds the version associated with the branch and hosts it at https://rdl-standard.readthedocs.io/en/.

Configuration

https://rdl-standard.readthedocs.io/en/latest redrirects to https://rdl-standard.readthedocs.io/en/main.

Automation rules are configured to:

• Activate, build and hide a new version when a commit is pushed to a new branch in the GitHub repository.
• Delete the associated version when a branch is deleted in the GitHub repository.

Pull request builds are also enabled.

Other than the main branch, all branches are hidden from the flyout menu.

Credentials

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

manage.py

The standard repository includes a command-line utility for administrative tasks. For information on the available commands, run ./manage.py --help.

pre-commit hooks

A pre-commit hook is used to format Markdown files in the docs directory.