This repository contains documentation resources for OpenDataSoft platform, APIs and tools.
All content in written in english, translations are managed with transifex at https://www.transifex.com/opendatasoft/documentation-5/ Please ask to join the group to contribute to the translation effort.
First, set up your Python installation (a virtualenv is recommended).
pip install -r requirements.txt
To be able to push to and retrieve from transifex the translation files (.po), you'll need to be a maintainer on the project. Once this is done, you'll have to configure your environment with:
tx init --user=<username> --pass=<password> sphinx-intl update-txconfig-resources --pot-dir build/locale --transifex-project-name documentation-5
Building the documentation
To build the documentation.
Please be aware that Sphinx builds fully independant pages and that it only builds pages that have changed since the last build. Which means you may experience different menus on different pages unless you clean the build directory beforehand.
rm -r build && make html
To list translatable strings and retrieve their translations from transifex:
To build the localized documentation (using translated strings from transifex):
The generated html will be available in
/build/html. You can either open the index.html file in your browser or do a
make server and go to
When building the documentation, you may run into an error about an unknown locale UTF-8. In that case you need to use the following:
export LC_ALL=en_US.UTF-8 export LANG=en_US.UTF-8
- Create a new branch for your work
- Create a pull request to develop
- Once the pull request is merged, you can work on the translations using "make translations"
The release works with a pull request into master and pushing the updated master branch to github.
Travis will then build the html documentation in all languages and deploy it.
Translations are managed through Transifex at https://www.transifex.com/opendatasoft/documentation-5/
Main documentation resources:
Build .pot files, push them to transifex and retrieve .po files
make gettext sphinx-intl update -p build/locale -l fr tx push -s tx pull -f fr
Build translated documentation
sphinx-intl build make -e SPHINXOPTS="-D language='fr'" html
Documentation is written in reStructuredText (rst). While not as popular as Markdown, it allows for richer pages.
The syntax reference is available at http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html but you should really start with http://sphinx-doc.org/rest.html.
You should strive to constrain the topic of each page to a single topic. Related topics should be placed within a same folder but topics should all have their dedicated pages.
- Write short sentences about simple concepts (as much as possible)
- Keep a neutral tone; the content should be easy to reuse inside a blog post or a newsletter for example
- Use present tense
- When describing steps, use imperative. e.g. "Click on this button, then type in the title..."
- When talking about OpenDataSoft as a company, use "us" or "OpenDataSoft"
1st level title =============== 2nd level title --------------- 3rd level title ~~~~~~~~~~~~~~~ 4th level title ^^^^^^^^^^^^^^^
To reference an internal page (here, the people.rst page in the company folder)
:doc:`Monty Python members </company/people>`
To reference any external page (note the trailing
`Monty Python members <https://en.wikipedia.org/wiki/Monty_Python>`_
If you have multiple links with the same name, then you will need to transform your named references into anonymous references by adding an extra
`link <http://google.com>`__ `link <http://google.fr>`__
To have a link send to a target="_blank", you need to use a substitution
Check this awesome |externalwebsite|
To a raw html with the target="_blank" parameter
.. |externalwebsite| raw:: html <a href="http://www.externalwebsite.com/" target="_blank">external website</a>
In an array, add an empty line:
* * GeoJSON * .json, .geojson * * :doc:`Geojson </extractors/geojson>`
All images should be named following this norm:
<doc_page_name>is the name of the
.rstfile the image is originally referenced from (using
_as tokens separator)
<image-name>is the name of the image itself, it should describe its content (using
-as tokens separator)
en(we do not support other languages in the documentation
If you need to annotate images (add circles, arrows, basic text), you can download Skitch (https://evernote.com/skitch/). It is free and very handy for these basic edits.
Icons from FontAwesome
To use an icon from FontAwesome, add a substitution between | (spaces are important)
Check this awesome |externalwebsite| |externallink|
To a raw html including the Font Awesome link
.. |externallink| raw:: html <i class="fa fa-external-link" aria-hidden="true"></i>
Note that the external link decorator is added automatically.