OGD Handbook Site

This repository contains web application source code for the OGD Handbook. For more information, visit http://handbook.opendata.swiss

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

1. Set up LFTP for syncing (one time)

sudo apt-get install lftp
mkdir ~/.lftp
echo "set ssl:verify-certificate no" > ~/.lftp/rc

2. Run deployment script

Re-run the publish command to ensure that assets are correctly formatted. Then upload to the server. You will be asked for an FTP password.

make publish
make ftp_upload

After deployment, ensure links are working in the Topics page, else you may need to re-run your publishing steps.

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.