Writing documentation¶
This section gives some guidelines to write consistent documentation for GeoNetwork.
See also
The quickest and easiest way to contribute to the documentation is to sign up for a GitHub account and edit the documentation pages (See code repository doc).
Build the docs¶
git clone https://github.com/geonetwork/doc
cd doc
mvn clean install
Edit the reStructuredText files¶
To update the documentation, use a text editor to edit .rst
files. 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.
Sphinx¶
This section gives some useful tips about using Sphinx.
Don’t introduce any new warnings¶
When building the doc, Sphinx prints out warnings about broken links, syntax errors, … 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
Links¶
Images¶
Place images in an img
folder in the directory where the rst file is
located. Use images with:
.. figure:: img/thumbprint.png
Reference to a section within a file¶
When creating a new page, add a reference on top of the file:
.. _writing-documentation:
This reference could then be used to link to that page or section:
:ref:`writing_documentation`
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¶
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¶
Use Sphinx’s versionadded
and 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.
...
Use deprecated
directive when a feature is no longer available.
seealso¶
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.