Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/okfn/opendatahandbook-old

Open Data Handbook
https://github.com/okfn/opendatahandbook-old

Last synced: 5 days ago
JSON representation

Open Data Handbook

Awesome Lists containing this project

README 

        
==================

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`_. 



.. _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



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/opendatahandbook/



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`_.



.. _restructured text: http://docutils.sourceforge.net/docs/user/rst/quickref.html



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 to HTML

------------------------------



Rendering the handbook in 'source' language (english). For rendering to other

languages see below.



1. Move into the base directory of the project::



    cd opendatahandbook



2. Install `Sphinx`_, with a minimum version of 1.1. Instructions for 

   Debian and Ubuntu::



    apt-get install python-sphinx



3. Make sure you have got the theme (provided by git submodule)::



    git submodule init

    git submodule update



4. Render the HTML, using ``make``::



    make html



Translations

------------



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.



1. Go to https://www.transifex.net/projects/p/opendatahandbook/

2. Add translation for specified language (and a team)



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).



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



   Note that is not a typo: you download the all.po**t** file but save it as

   all.po (no t!).



2. Build the mo file::



    make msgfmt lang={lang}



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}



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::



  # 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}

  # this would usually be git add {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



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

- note edit index.html in gh-pages branch not master!).