编写文档¶
本节提供了一些编写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项目。