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
_.
.. _our wiki: http://wiki.okfn.org/Projects/Open_Data_Handbook#Contributing .. _half an hour: http://wiki.okfn.org/Projects/Open_Data_Handbook#Micro-tasks .. _larger tasks: http://wiki.okfn.org/Projects/Open_Data_Handbook#Sections_that_need_authors
: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/opendatahandbook/
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
.
.. _restructured text: http://docutils.sourceforge.net/docs/user/rst/quickref.html
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 in 'source' language (english). For rendering to other languages see below.
Move into the base directory of the project::
cd opendatahandbook
Install Sphinx
_, with a minimum version of 1.1. Instructions for
Debian and Ubuntu::
apt-get install python-sphinx
Make sure you have got the theme (provided by git submodule)::
git submodule init git submodule update
Render the HTML, using make
::
make html
Building the English Source 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/opendatahandbook/.
Updating the Translation with New Source Text
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.
.. _Open Data Handbook: http://opendatahandbook.org/ .. _Open Knowledge Foundation: http://okfn.org/ .. _Sphinx: http://sphinx.pocoo.org/
Adding Translations +++++++++++++++++++
We use transifex for this.
Building a translation of the handbook ++++++++++++++++++++++++++++++++++++++
Note: you should do steps 1-3 in the master
branch (and committed there).
Step 4 would only be committed as part of Deploying (see next section).
Download the translated all.pot file and copy it to (where lang
is a 2-digit ISO code <http://en.wikipedia.org/wiki/ISO_3166-1>
_)::
translation/{lang}/LC_MESSAGES/all.po
Note that is not a typo: you download the all.pot file but save it as all.po (no t!).
Build 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}
Deploying the Handbook ++++++++++++++++++++++
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::
git checkout gh-pages git merge master
make html lang={your-lang}
make github lang={your-lang}
git status
git add {relevant-files} git commit -m "[build][s]: build latest version of language ..."
git push
Note: if you are adding a new translation you will want to add it to the dropdown list at the top of the index.html file (index.html in this root folder