Open Data Handbook
Python
Pull request Compare This branch is 119 commits behind okfn:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.tx
bin
source
translation
.gitignore
.gitmodules
Makefile
README.rst
index.html

README.rst

Open Data Handbook

Introduction

Welcome to the source text of the Open Data Handbook. The handbook is a project of the Open Knowledge Foundation. If you are reading this it is likely you are looking to contribute in some way, whether that's translation, feedback, editing or adding more content. If you just want to read the handbook, then please head over to the http://opendatahandbook.org/.

Contributing

We have several ways you can help. The project is split into a few roles. Our authors write content, editors merge those submissions into the handbook, designers help beautify it and translators bring the handbook to all countries of the world.

Our wiki is a great place to get started. It contains a large number of tasks for people with half an hour as well as larger tasks.

Resources

Home Page:http://wiki.okfn.org/Projects/Open_Data_Handbook
Mailing List:http://lists.okfn.org/mailman/listinfo/open-data-manual
Source:https://github.org/okfn/opendatahandbook
Translations:https://www.transifex.net/projects/p/opendatamanual/

About our tools

The handbook is written the ReStructured Text format. ReStructured Text allows us to write files in plain text files, which can be nicely rendered as a website or a PDF using Sphinx.

Project Layout

Outline:

opendatahandbook/
  source/
  bin/
  build/
  translation/

Details:

opendatahandbook is the base directory.

source is where we keep the plain text source files.

bin is short for binaries, or executable commands. This folder holds handy scripts.

build is where rendered, or "built", HTML files live.

translation is where our i18n files are kept

Rendering the handbook

  1. Move into the base directory of the project:

    cd opendatahandbook
    
  1. Install Sphinx, with a minimum version of 0.6. Instructions for Debian and Ubuntu:

    apt-get install python-sphinx
    
  2. Render the HTML, using make:

    make html
    

Building for Translation (i18n)

Important. You will need to install Sphinx >= v1.1 for this to work.

Generating pot files

  1. Extract translateable sentences/paragraphs:

    make gettext
    
  2. Add or update the translated/all.pot file as a resource on https://www.transifex.net/projects/p/opendatamanual/.

Adding a new language

We use transifex for this.

  1. Go to https://www.transifex.net/projects/p/opendatamanual/
  2. Add translation for specified language (and a team)

Building a translation of the handbook

  1. Download the translated all.pot file and copy it to (where lang is a 2-digit ISO code):

    translation/{lang}/LC_MESSAGES/all.po
    
  2. Build the mo file. In the directory of the all.po file do:

    msgfmt all.po -o all.mo
    
  3. Symlink from all.mo (sphinx expects us to have kept with original file names generated by gettext rather than concatenating):

    make linkpot lang={lang}
    
  4. Build the translation:

    make html lang={lang}