wiki:the_docs_strikes_back

Version 4 (modified by cvvergara, 7 years ago) ( diff )

doing some fixes

TOC

Part 2 of building the docs, this will be about .po files generation and the Transifex workflow.

Logs

Inspiration : ​https://github.com/cvvergara/OSGeoLive-doc/tree/aurebesh/locale

Installing Transifex client

sudo pip install transifex-client

# check it is working
tx --version # 0.12.4 when writing this documentation

If you followed the previous part ​Building the docs, the pot files are already made. 

# pot files of the source language (english)
ls -R locale/pot

# po file for the locales (e.g. Spanish)
ls -R locale/es

The pot files are pushes to the repository (see this file for change it).

Updating the files

When we build the locale with CMakeLists.txt, the gettext command is called, so all the po files are updated at the same time.

see the ​locale command 

sphinx-intl update-txconfig-resources --pot-dir locales/pot --transifex-project-name osgeolive

Pushing to Transifex

The configuration for Transifex (.tx/config) should have been done automatically. So we only need to push the updates to the Transifex platform

tx push -s It can be interesting to assign a category to freshly pushed resources, so you can sort them easily.

Auto Update

Transifex can be configured to check files twice a day and update them. Please see this link for more information about it:

​https://docs.transifex.com/projects/updating-content/#automatically-updating-source-files

Rebuild the .pot files

Make sure build directory is empty

rm -rf build/* Build the pot/po files 

cd build
cmake  -DLOCALE=ON ..
make locale > locale_log.txt
cd ..

List .pot files

ls -R locale/pot List a language's .po files for example spanish:

ls -R locale/es Then to update Transifex:

tx push -s

Prioritizing the translations

locking older versions

Some files, like standards are kept but not upgraded. So there is no need to translate them. It is possible to lock them, in the Resource Settings and untick the option "Your translators can translate resource strings".

Translation priority

This cna be set with the up ">" at the right of the resource. There is 3 possilities

  • Urgent : 2 red ">"
  • High : 1 yellow ">"
  • normal : 1 green "-"

Put retired or non translated docs to normal. Osgeo-live related docs are set to "Urgent".

Fixing errors

Mismatch error

If you get a Mismatch: both interpreted text role prefix and reference suffix. error it might means that a string as prefix that is not recognized.

For example this english string:

Geospatial algorithms, including those from :doc:`JTS `, can be called through GeoServer's `WPS <http://www.opengeospatial.org/standards/wps>`__ interface. This includes the chaining of processes, and using rendering transformations to create powerful visualisations through the WMS interface. is translated in French to:

Des algorithmes géospatiaux, incluant ceux venant de :doc:`JTS `, peuvent être appelés via l'interface :doc:`WPS <http://www.opengeospatial.org/standards/wps>`__ de GeoServer. Cela inclue le chaînage de traitements, et l'utilisation de transformations de rendu pour créer des visualisations puissantes via l'interface WMS. Do you see the surplus :doc: ?

Yes right before WPS ! :doc: are use to link to document in the documentation, but it is a link to the WPS webpage. So sphinx doesn't find the WPS <http://www.opengeospatial.org/standards/wps> file and gives an error.

How to document the overview file

The overview files are located at:

​https://github.com/OSGeo/OSGeoLive-doc/tree/master/doc/overview

For this documentation:

  • Words surrounded by < > are to be defined by the person documenting the project
    • <slug> is the slug name defined on projects_info.csv file
  • The project overview file name is <slug>_overview.rst for example udig_overview.rst
  • Words surrounded by @ are variables and will automatically get values, the purpose is to keep consistency through all the documentation
Table Header Example Action
@LOGO_<slug>@ @LOGO_udig@ Gets the logo image of the project if it exists
@OSGEO_KIND_<slug>@ @OSGEO_KIND_udig@ Gets the logo of the kind of project within OSGeo
@NAME_udig@ @NAME_udig@ Gets the name of the project as defined on the projects_info.csv
@QUICKSTART_udig@ @QUICKSTART_udig@ Will generate a link to the quickstart if it exists

and has the following structure: 

:Author: <author's name>
:Reviewer: <reviewer name>
:Version: <OSGeoLive version from which this documentation is valid>
:License: Creative Commons Attribution 3.0 Unported (CC BY 3.0)


@LOGO_<slug>@
@OSGEO_KIND_<slug>@


@NAME_<slug>@
================================================================================

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris eget dui vitae est
sodales consequat eget vel risus. Fusce suscipit lorem sit amet elementum volutpat.
Praesent pretium mauris id porta convallis. Integer suscipit, massa at tempor congue,
lectus ipsum tempor eros, non elementum orci felis eget diam. Praesent vitae tortor
finibus, bibendum orci vulputate, semper lectus. Morbi fringilla dignissim consectetur.

Donec ac dictum nisi. Cras sed justo id augue lacinia tincidunt vel non purus.
Doneceget ante blandit leo porta semper eu in sapien. Donec at nibh finibus,
posuere eros eget, fringilla tortor. Morbi quam @NAME_<slug>@  together with
@NAME_<other_slug>@ ipsum, molestie et mi nec,
bibendum feugiat ipsum. Fusce mauris ligula, iaculis id varius a, laoreet nec lectus.
Phasellus rhoncus pulvinar purus.

@NAME_<slug>@  Praesent quis sapien nibh. Integer dictum, augue sed semper tincidunt,
lectus sem porttitor mauris, a porta magna est a orci.


@SCREENSHOT_<slug>@

Core Features
--------------------------------------------------------------------------------

* Vestibulum massa risus
* sagittis eu ornare ut
* dapibus sit amet risus

Implemented Standards
--------------------------------------------------------------------------------

* OGC Web Map Server (WMS)
* OGC Web Feature Server (WFS)


Details
--------------------------------------------------------------------------------

**Website:** <wesite link>

**Licence:** <license>

**Software Version:** |version-udig|

**Supported Platforms:** <List of platforms>

**API Interfaces:** <list of API interfaces>

**Support:** <support link>

**Developers:** <developers link>


@QUICKSTART_udig@

.. presentation-note
    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris eget dui vitae est
    sodales consequat eget vel risus. Fusce suscipit lorem sit amet elementum volutpat.
    Praesent pretium mauris id porta convallis. Integer suscipit, massa at tempor congue,
    lectus ipsum tempor eros, non elementum orci felis eget diam. Praesent vitae tortor
    finibus, bibendum orci vulputate, semper lectus. Morbi fringilla dignissim consectetur.
Note: See TracWiki for help on using the wiki.