OGD Handbook Site

This repository contains web application source code for the previous version of the OGD Handbook. For the current OGD Handbook code, see https://github.com/opendata-swiss/ogdch-handbook.

This version of the Handbook site is currently deployed to http://opendata-swiss.github.io/ogd-handbook-site/pages/index for archiving.

Overview

The web frontend for the OGD Handbook is documented here. We use the Pelican static site generator for Python which you can learn about at docs.getpelican.com. It can be easily and quickly deployed to any standard web server, as detailed below.

The Handbook content is written using Markdown. This is maintained in a separate repository submoduled under content/handbook.

The Python-based wiki realms.io was used to create a collaborative environment for editing content, see deployment instructions. We are using our own fork with Docker-based customizations.

We are using the Pelican Bootstrap 3 theme. For more information see the project's homepage, Pelican's documentation on themes, and the Bootstrap site.

The following documentation deals with installation of the web frontend.

Setup

1. Clone this repository, then go into the folder and update submodules:

git submodule update --init --recursive

2. Create and initialise the virtual environment:

virtualenv .venv
. .venv/bin/activate
pip install -r requirements.txt

3. Run the development server

./develop_server.sh start 8080

You can now access the website on http://localhost:8080

If you see a "Directory listing", then restart the server - this is a known Pelican weirdness:

./develop_server.sh stop
./develop_server.sh start 8080

Configuration

Please see Pelican documentation for information on configuring for deployment.

Contribution guidelines

We accept pull requests to this repository for changes to the web site only.

Deployment notes

The master branch of this repo is automatically deployed to GitHub Pages.

Document export

To generate document versions of the Handbook pages, we use pandoc. The latest version (1.15+ is required) can be installed by downloading a binary from this page.

To also create Word (DOCX) files, you need to install LibreOffice and unoconv (i.e. sudo apt-get install libreoffice unoconv).

The files will then be generated in the /export folder of output using:

make doc_export

Note: if you are seeing an ERROR: No module named 'uno' error: copy /usr/bin/unoconv to /usr/local/bin/unoconv, and replace #!/usr/bin/env python3 to just #!/usr/bin/python3 in this file.

Translations

Using Babel for Flask, we can keep the theme translations up to date. Use the script in the root folder:

./update_translations.sh

To add another language:

cd theme/translations
pybabel init -i messages.pot -d . -l de

Who do I talk to?

Send us a note via the contacts on the homepage if you have a question.