Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Build & translation / Add all informations in the same guide. #83

Merged
merged 1 commit into from
Nov 26, 2019
Merged

Build & translation / Add all informations in the same guide. #83

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
89 changes: 1 addition & 88 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,92 +1,5 @@
# Project documentation module

The documentation use [RST format](http://sphinx-doc.org/rest.html).
Check the ["Writing documentation" guide](https://geonetwork-opensource.org/manuals/3.8.x/en/contributing/writing-documentation.html).

**All translations should be done on Transifex web interface. No properties files should be committed to this repository.**

## Updating the documentation

If you add some new section or update the text on an existing section, you have to update the transifex fields to make sure this change is spread to all languages. To achieve this, execute:

```
make update_translations
```

## How to build the documentation

### Installing the tools

To build the documentation you need to have [make](https://www.gnu.org/software/make/) installed in your system:
```
sudo apt-get install make
```

Sphinx is required to build documentation.See http://sphinx-doc.org/latest/install.html.
You can install it with [pip](https://pip.pypa.io/en/stable/installing/):
```
sudo easy_install pip
sudo pip install sphinx
```

The theme is based on [sphinx_rtd_theme](https://github.com/snide/sphinx_rtd_theme) and the sphinx_bootstrap_theme.
You can install the style with pip too:
```
sudo pip install sphinx-bootstrap-theme
sudo pip install sphinx_rtd_theme
```

The internationalization is build using [sphinx-intl](http://www.sphinx-doc.org/es/stable/intl.html):

```
sudo pip install sphinx-intl
```

To download the translations from Transifex, you will need the transifex command line client:
https://docs.transifex.com/client/installing-the-client
The Transifex Client is written in Python, so it runs on most systems. The easiest way to install it is with pip:

```
sudo pip install transifex-client
```
If you don't want to use the transifex-client, either you will have to manually download the translated files or you will only be able to build the English version of the documentation.

### Configuring your local

And then you need to configure your transifex user:
https://docs.transifex.com/client/client-configuration
~/.transifexrc stores your Transifex.com credentials. This config file is unique per user, and it's stored in your home directory.

```
[https://www.transifex.com]
username = your_username/api
token =
password = p@ssw0rd/api_token
hostname = https://www.transifex.com
```
### Building the documentation

To build the documentation, run:

```
mvn clean install
```

This will build all documentation in English only.

To build all documentation in several languages (right now: es,fr,ge,it,ko,nl,cz,ca,fi,is), based on transifex translations:

```
mvn clean install -Pall
```

If you want to get the latest translations for your build, run:

```
mvn clean install -Platest,all
```

#### Adding a new language

If you want to add a new language to the build, you will have to edit the file https://github.com/geonetwork/doc/blob/develop/Makefile#L59 and add the languages you want to build the documentation for.

If you want it to be publicly available on geonetwork-opensource.org webpage, make sure you make a PR with the change and ask for advice on the https://github.com/geonetwork/website project.
83 changes: 78 additions & 5 deletions source/contributing/writing-documentation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ for |project_name|.
.. seealso::

The quickest and easiest way to contribute to the documentation is to sign up
for a `GitHub account <https://github.com/>`_ and edit the documentation pages by clicking the
for a `GitHub account <https://github.com/>`_ and edit the documentation pages by clicking the
"Edit on GitHub" link at the top of the page. (See :repo:`doc`).


Expand All @@ -21,12 +21,25 @@ Building the docs

The following tools are required to build the documentation from source:

* **Java JDK 1.8**
* **Java JDK 1.8**, **Python**
* **Maven 3.1.0+**: Once installed `Maven <https://maven.apache.org>`_ should be available in your command shell as ``mvn``.
* **make**: Once installed `make <https://www.gnu.org/software/make/>`_ should be available in your command shell as ``make``.
* **Sphinx**: See `Sphinx <https://www.sphinx-doc.org/en/master/usage/installation.html>`_ for details. Once installed confirm it's available by running ``sphinx-build --version``.
* **sphinx-bootstrap-theme**: Install using ``pip install sphinx-bootstrap-theme``.

Then build the documentation using the following commands:
* **sphinx-bootstrap-theme**.

To install the build tools:

.. code-block:: shell

sudo apt install make
sudo apt install python3-pip
sudo pip install sphinx
sudo pip install sphinx-bootstrap-theme
sudo pip install sphinx_rtd_theme



Then build the documentation in English using the following commands:

.. code-block:: shell

Expand All @@ -37,6 +50,22 @@ Then build the documentation using the following commands:
Once the documentation has built without errors, access the html files from ``doc\target\en\index.html``.


To build all documentation in several languages (right now: es,fr,ge,it,ko,nl,cz,ca,fi,is), based on transifex translations:

.. code-block:: shell

mvn clean install -Pall


If you want to get the latest translations for your build, run:

.. code-block:: shell

mvn clean install -Platest,all




Editing the reStructuredText files
==================================

Expand Down Expand Up @@ -199,3 +228,47 @@ Many sections include a list of references to module documentation or external
documents. These lists are created using the ``seealso`` directive
typically placed in a section just before any subsections.



Translating the doc
===================

`Github doc repository <https://github.com/geonetwork/doc>`_ contains the English version of the documentation. All translations should be done on Transifex web interface. No properties files should be committed to this repository.

If you add some new section or update the text on an existing section, you have to update the transifex fields to make sure this change is spread to all languages. To achieve this, execute:

To download the translations from Transifex, you will need the transifex command line client:
https://docs.transifex.com/client/installing-the-client. The Transifex Client is written in Python, so it runs on most systems. The easiest way to install it is with pip.


To install the build tools:

.. code-block:: shell

sudo pip install sphinx-intl
sudo pip install transifex-client


Once installed, you need to configure your transifex user: https://docs.transifex.com/client/client-configuration in `~/.transifexrc`. This config file is unique per user, and it is stored in your home directory.


.. code-block:: none

[https://www.transifex.com]
username = your_username/api
token =
password = p@ssw0rd/api_token
hostname = https://www.transifex.com


Update translations on transifex:

.. code-block:: shell

make update_translations



If you want to add a new language to the build, you will have to edit the file https://github.com/geonetwork/doc/blob/develop/Makefile#L59 and add the languages you want to build the documentation for.

If you want it to be publicly available on https://geonetwork-opensource.org webpage, make sure you make a PR with the change and ask for advice on the https://github.com/geonetwork/website project.