编写文档

本节提供了一些编写GeoNetwork一致性文档的指南。

参见

对文档做出贡献的最快和最简单的方法是注册 GitHub account 并通过单击页面顶部的“在GitHub上编辑”链接来编辑文档页面。（见 code repository doc ）

构建文档

从源代码构建文档需要以下工具：

• Java JDK 1.8版 ， Python

• 马文3.1.0+ ：一旦安装 Maven 应在命令shell中作为 mvn .

• make ：一旦安装 make 应在命令shell中作为 make .

• Sphinx 见 Sphinx 详细情况。一旦安装，通过运行 sphinx-build --version .

• sphinx-bootstrap-theme .

要安装生成工具，请执行以下操作：

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

然后使用以下命令生成英文文档：

git clone https://github.com/geonetwork/doc
cd doc
mvn clean install

一旦文档构建无误，就可以从 doc\target\en\index.html .

基于Transifex翻译，以几种语言（目前：es、fr、ge、it、ko、nl、cz、ca、fi、is）构建所有文档：

mvn clean install -Pall

如果要获取生成的最新翻译，请运行：

mvn clean install -Platest,all

建立标准文档

重要

有关标准和编辑器配置的文档是使用 schema-doc 插件。因此，不要手动编辑以下文件：

• 文件/手册/来源/附件/标准/*

• 文档/手册/来源/自定义应用程序/编辑器用户界面/创建自定义-编辑器.rst

不要在Transifex中翻译这些文件。翻译必须在插件本身完成。要更新这些文件，请克隆GeoNetwork存储库并使用以下命令：

cd docs/schema-doc
mvn clean install

检查更新的文件并提交到文档存储库。

编辑重新构造的文本文件

要更新文档，请使用文本编辑器编辑 .rst 文件夹。通过检查确保使用正确的术语 样式指南 . 保存更改，生成文档并打开HTML文件以预览更改。当您的更改准备好提交到项目时，请按照中的步骤 发出请求 .

Sphinx

本节提供一些关于使用 Sphinx 的有用提示。

不要引入任何新的警告

在构建文档时，Sphinx会打印出关于断开链接、语法错误等的警告。不要介绍新的。

最好删除生成目录并完全重新生成文档，以检查是否有任何警告：

mvn clean install

链接

图像

将图像放置在 img rst文件所在目录中的文件夹。将图像用于：

.. figure:: img/thumbprint.png

代码块

使用以下指令突出显示代码块：

.. code-block:: xml

引用文件中的节

创建新页时，请在文件顶部添加引用：

.. _writing-documentation:

此引用可用于链接到该页或节：

:ref:`writing_documentation`

链接到GitHub资源

这个形态py包含一组 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

示例，链接到Bern用户会议（请参见 wiki page Meeting2015Bern ）

替代品

Substitutions 对于定义许多地方需要的值（例如文件的位置等）很有用。

这些值在 rst_epilog 在形态py:

.. |jdbc.properties| replace:: WEB-INF/config-db/jdbc.properties

适当时使用：

Configure the database in |jdbc.properties| ...


After installation look to |install.homepage|_ on your web browser.

versionadded、versionchanged和deprecated

使用 Sphinx 的 versionadded 和 versionchanged 用于标记新功能或已更改功能的指令。例如：

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.

...

当使用 versionchanged 指令，解释变化的句子通常是相关的：

Configuring LDAP
================

.. versionchanged:: 2.10.0
   Previous versions was setting LDAP parameters from the administration
   panel.

...

使用 deprecated 当功能不再可用时的指令。

锯齿波

许多部分包括对模块文档或外部文档的引用列表。这些列表是使用 seealso 指令通常放在任何子节前面的节中。

翻译文档

Github doc repository 包含文档的英文版本。所有翻译都应该在Transifex的web界面上完成。不应将任何属性文件提交到此存储库。

如果您添加一些新的节或更新现有节上的文本，则必须更新Transifex字段以确保此更改传播到所有语言。为此，请执行以下操作：

要从Transifex下载翻译，您需要Transifex命令行客户端：https://docs.transifex.com/client/installing-the-client。Transifex客户机是用Python编写的，因此它可以在大多数系统上运行。最简单的安装方法是使用pip。

要安装生成工具，请执行以下操作：

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

安装后，您需要配置Transifex用户：https://docs.transifex.com/client/client-configuration在里面 ~/.transifexrc . 此配置文件对每个用户都是唯一的，并且存储在主目录中。

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

在Transifex上更新翻译：

make update_translations

如果要向生成中添加新语言，则必须编辑该文件https://github.com/geonetwork/doc/blob/develop/Makefile#L59并添加要为其生成文档的语言。

如果你想公开的话https://geonetwork-opensource.org网页，确保你做了一个公关与变化，并征求意见https://github.com/geonetwork/website项目。