IATI/IATI-Standard-SSOT

Single Source of Truth (SSOT) for IATI

IATI Standard SSOT

Introduction

This is the main github repository for the IATI Standard Single Source of Truth (SSOT). For more detailed information about the SSOT, please see http://iatistandard.org/developer/ssot/

Building the documentation

Requirements:

• Git
• Unix based setup (e.g. Linux, Mac OS X) with bash etc.
• Python 3.x
• gcc
• Development files for libxml and libxslt e.g. libxml2-dev, libxslt-dev

Fetch the source code::

git clone https://github.com/IATI/IATI-Standard-SSOT.git

Pull in the git submodules::

git submodule init
git submodule update

Set up a virtual environment:

# Create a virtual environment (recommended)
python3 -m venv pyenv

# Activate the virtual environment if you created one
# This must repeated each time you open a new shell
source pyenv/bin/activate

# Install python requirements
pip install -r requirements.txt

Build the documentation::

./gen.sh

The built documentation is now in docs/<language>/_build/dirhtml

Editing the documentation

Make any changes in IATI-Extra-Documentation, as the docs directory is generated from this and other sources each time ./gen.sh is run.

Building a website that also includes additonal guidance

There is additonal guidance in the following git repositories:

• https://github.com/IATI/IATI-Guidance
• https://github.com/IATI/IATI-Developer-Documentation/

These are not versioned with the standard, so are not included in this repository (IATI-Standard-SSOT) or its submodules.

To generate a copy of the website with these extra repositories included, run:

# If you have not done already create the docs directory as a git repository
# (more info below)
mkdir docs
cd docs
git init
cd ..
# Actually run the generate script
./combined_gen.sh

This generates the website in the docs directory, but then copies it to docs-copy at the end, so that a webserver can be pointed to docs-copy/en/_build/dirhtml and not be interrupted when the site is being rebuilt.

The docs directory should be a git repository in order to support adding the "Last updated" line to the bottom of the page. We build the live and dev websites in different directories so that the last updated date corresponds to when the site was actually changed, not when the relevant commit was added to the source git respository.

Generating a local version with the IATI theme

A local version of the website (with the full IATI theme) can be generated after cloning the theme files and setting up the required symlinks for Sphinx to follow when generating the HTML files.

# Clone the repository containing the IATI theme at the same level where you cloned IATI-Standard-SSOT
git clone https://github.com/IATI/IATI-Websites.git IATI-Websites

# Set-up symlinks to the template file/folders
# for the symlinks to work, you'll have to be inside the IATI-Extra-Documentation folder cloned inside IATI-Standard-SSOT
cd IATI-Extra-Documentation/en
ln -s ../../../IATI-Websites/iatistandard/_templates/ ./
ln -s ../../../IATI-Websites/iatistandard/_static/ ./
ln -s ../../../IATI-Websites/iatistandard/_templates/layout_dev.html ./_templates/layout.html

# Generate a version of the documentation
cd ../../
./combined_gen.sh

# The documentation HTML files are stored in the `docs-copy/en/_build/dirhtml` folder
# You can navigate around your generated version of the site using a Python HTTP webserver
cd docs-copy/en/_build/dirhtml
python3 -m http.server
# View the site in a browser at http://0.0.0.0:8000/