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/.
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.
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.
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 keptMove into the base directory of the project:
cd opendatahandbook
Install Sphinx, with a minimum version of 0.6. Instructions for Debian and Ubuntu:
apt-get install python-sphinx
Render the HTML, using
make:make html
Important. You will need to install Sphinx >= v1.1 for this to work.
Extract translateable sentences/paragraphs:
make gettext
Add or update the
translated/all.potfile as a resource on https://www.transifex.net/projects/p/opendatahandbook/.
We use transifex for this.
- Go to https://www.transifex.net/projects/p/opendatahandbook/
- Add translation for specified language (and a team)
Download the translated all.pot file and copy it to (where
langis a 2-digit ISO code):translation/{lang}/LC_MESSAGES/all.poBuild the mo file:
make msgfmt lang={lang}Symlink from all.mo (sphinx expects us to have kept with original file names generated by gettext rather than concatenating):
make linkpot lang={lang}Build the translation:
make html lang={lang}
Simple version: just upload a new all.pot to transifex.
WARNING: this will immediately update all translation files and will usually discard any translations of strings that have changed however the trivial the change is.
We use github pages to host the handbook at the present (in the past we have used s3 and readthedocs).
As such the exact version of the html we want served should be in the gh-pages branch of this repo.
The following as walkthrough of a deployment:
# change gh-pages branch and get all latest changes to material
git checkout gh-pages
git merge master
# build the relevant languages (if not already built)
make html lang={your-lang}
# copies build version to /{lang}/ so it is right location for website
# also does some tidying up (delete files that are not needed)
make github lang={your-lang}
## now you will want to commit changes
# take a look at what has changed
git status
# add relevant files
# e.g. add *all* changes for the lang you updated git add -u {lang}
git add {relevant-files}
git commit -m "[build][s]: build latest version of language ..."
# push changes up
# this will auto-update http://opendatahandbook.org/
# up until this moment nothing will have changed on the website
git push