This section provides some guidelines for writing consistent documentation for GeoNetwork.
The quickest and easiest way to contribute to the documentation is to sign up for a GitHub account and edit the documentation pages by clicking the “Edit on GitHub” link at the top of the page. (See code repository doc).
Building the docs¶
The following tools are required to build the documentation from source:
Java JDK 1.8, Python
Maven 3.1.0+: Once installed Maven should be available in your command shell as
make: Once installed make should be available in your command shell as
Sphinx: See Sphinx for details. Once installed confirm it’s available by running
To install the build tools:
sudo apt install make sudo apt install python3-pip sudo pip install sphinx sudo pip3 install sphinx-bootstrap-theme sudo pip3 install sphinx_rtd_theme
Then build the documentation in English using the following commands:
git clone https://github.com/geonetwork/doc cd doc mvn clean install
Once the documentation has built without errors, access the html files from
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
Building the standards docs¶
Documentation about the standards and the editor configuration is built from the GeoNetwork source code using the
schema-doc plugin. So do not manually edit the following files:
Do not translate those files in Transifex. Translation must be done in the plugin itself. To update those files, clone the GeoNetwork repository and use the following commands:
cd docs/schema-doc mvn clean install
Check the updated files and commit to the doc repository.
Editing the reStructuredText files¶
To update the documentation, use a text editor to edit
.rst files. Ensure you are using the correct terminology by
checking Style Guide. Save
your changes, build the documentation and open the HTML files to preview
the changes. When your changes are ready to be submitted to the project, follow
the steps in Making a pull request.
This section gives some useful tips about using Sphinx.
Don’t introduce any new warnings¶
When building the docs, Sphinx prints out warnings about broken links, syntax errors and so on. Don’t introduce new ones.
It’s best to delete the build directory and completely rebuild the docs, to check for any warnings:
mvn clean install
Place images in an
img folder in the directory where the rst file is
located. Use images with:
.. figure:: img/thumbprint.png
Use the following directive to highlight code block:
.. code-block:: xml
Reference to a section within a file¶
When creating a new page, add a reference on top of the file:
This reference could then be used to link to that page or section:
Link to GitHub resources¶
The conf.py contains a set of external links definition.
* :issue:`123` to link to an issue * :pr:`123` to link to a pull request * :code:`web/pom.xml` to link to a file in the source code * :repo:`schema_plugins` to link to a repository * :wiki:`Meeting2015Bern` to link to a wiki page
Example, link to the Bern User Meeting (See wiki page Meeting2015Bern).
Substitutions are useful to define a value that’s needed in many places (eg. the location of a file, etc.).
The values are defined in
rst_epilog in conf.py:
.. |jdbc.properties| replace:: WEB-INF/config-db/jdbc.properties
Use them when appropriate:
Configure the database in |jdbc.properties| ... After installation look to |install.homepage|_ on your web browser.
versionadded, versionchanged and deprecated¶
versionchanged directives to mark new or
changed features. For example:
Creating overview from WMS ========================== .. versionadded:: 3.0 In the *add overview panel*, select the *add from WMS* link to create an image from the WMS referenced in the metadata record to illustrate the dataset in a specific area. ...
When using the
versionchanged directive, a sentence explaining what
changed is usually relevant:
Configuring LDAP ================ .. versionchanged:: 2.10.0 Previous versions was setting LDAP parameters from the administration panel. ...
deprecated directive when a feature is no longer available.
Many sections include a list of references to module documentation or external
documents. These lists are created using the
typically placed in a section just before any subsections.
Translating the doc¶
Github doc repository 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:
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.
[https://www.transifex.com] username = your_username/api token = password = p@ssw0rd/api_token hostname = https://www.transifex.com
Update translations on Transifex:
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#L65 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.