贡献#

贡献代码#

待续

汇报错误#

待续

撰写文档#

主文档是通过 reStructuredText 来进行书写，并且使用 sphinx 来生成。在线文档通过 ReadTheDocs 平台来进行托管.

文档已经在Windows 11 (开发平台)和Linux (ReadTheDocs平台)通过了构建测试。由于python的跨平台特性，在macOS上构建文档应该也可行但是没有进行过官方测试。

备注

如果你发现了官方文档中的任何错误，非常欢迎修复它并提交一个合并请求(Fork -> clone -> 在本地定位 -> 修改 -> 预览生成的html文件 -> 提交合并请求)

先决依赖#

你需要用下面的代码来安装python依赖(请先确保激活了虚拟环境)

(venv)> pip install -r requirements/docs.txt

为了处理jupyter笔记本，需要在电脑上安装 pandoc 。

用下面的命令来确认是否安装成功：

(easyidp) % pandoc --version
pandoc 2.18
Compiled with pandoc-types 1.22.2, texmath 0.12.5, skylighting 0.12.3,
citeproc 0.7, ipynb 0.2, hslua 2.2.0
Scripting engine: Lua 5.4
...

Then please download all datasets, this may take a long time.

>>> import easyidp as idp
>>> idp.data.dowload_all()

编译#

在克隆了EasyIDP仓库后，激活虚拟环境然后进入 docs 文件夹

(venv) EasyIDP> cd docs
(venv) EasyIDP/docs>

然后你可以通过下面的方法来构建文档：

(venv) EasyIDP/docs> make html

你可以打开 _build\html\index.html 文件来查看生成的文档

翻译文档#

我们在这里使用 sphinx-intl 来提供多语言文档。如果你想帮助翻译你的母语，请遵循下面的指引或者参考官方文档 :

1. 提取可翻译的句子#

首先，把文档中的可翻译句子提取到pot文件里：

(venv) EasyIDP/docs> make gettext

它会调用sphinx编译器，在 _build/gettext 文件夹下生成 *.pot 文件

小心

请仔细的检查这边的输出，是否有任何的警告或报错。直到他们被修复并不在出现前，不要运行下面的代码

2. 准备翻译文件#

然后，使用下面的代码来把之前的断句转换成对应的语言文件夹( _locale\<your-lang> )下的翻译文件

(venv) EasyIDP/docs> sphinx-intl update -p _build/gettext -l zh_CN -l ja

2.0.0.dev2
Not Changed: locale/zh_CN\LC_MESSAGES\backgrounds.po
Not Changed: locale/ja\LC_MESSAGES\backgrounds.po
...
Not Changed: locale/zh_CN\LC_MESSAGES\python_api.po
Not Changed: locale/ja\LC_MESSAGES\python_api.po

备注

最后部分的 -l zh_CN -l ja 意为翻译成中文(zh_CN)和日语(Ja)。如果你需要翻译另一个语言，直接在后面再添加一个 -l xxx ，语言代码 xxx 可以从这里找到

小技巧

如果你想让你翻译的语言出现在 readthedocs 官方文档中，请先在本地翻译好，然后再提交一个合并请求(pull request), 只需要提交 docs\locale\<your-lang>\LC_MESSAGES 文件夹。当它通过了我们的审核，我们会尽快开放对应的链接。

3. 翻译#

这是最耗时的步骤。请先仔细检查上面步骤的输出，有哪些文件改变了。然后检查 _locale\<your-lang>\LC_MESSAGES 文件夹并编辑修改了的文件。

小技巧

The *.po files have the following formats:

#: ../../contribute.rst:5
msgid "Contribute"
msgstr ""

第一行说明它出现的地点，第二行展示了原文，第三行是你需要输入的翻译

有时候，它会出现一行 #, fuzzy :

#: ../../contribute.rst:5
#, fuzzy
msgid "Contribute"
msgstr ""

这表示原文产生了改变，请再次检查翻译。

请做下面的几步：

检查之前的输出中提及哪些文件改变了，然后对于每一个改变的文件
在代码编辑器中按 Ctrl + F 来查找是否有 #, fuzzy 存在，先修改这些语句
如果有任何 msgstr "" 语句存在的话，不一定都需要翻译。比如EasyIDP, Python这样的就不需要翻译，直接留空就行。

备注

如果句子太长，通过在新的一行添加 “” 即可连接句子

msgstr "This sentence is too long"
"But it is okay to continue like this"
"and this ..."

但是不应该有任何空行

小心

对于行内代码和链接，请确保他们前后有空格存在

OK  -> Press ``Ctrl`` + `url <url>`_ in your
ERR -> Press``Ctrl``+ `url <url>`_in your

否则这些句子会报错但没有任何提示，你的翻译也不会出现

4. 渲染并预览#

最后，改变渲染和本地预览的语言( -Dlanguage='your_lang' )，然后生成文档：

Windows

(venv) EasyIDP/docs> set SPHINXOPTS=-Dlanguage=zh_CN
(venv) EasyIDP/docs> make html

Linux/BSD

(venv) EasyIDP/docs> make -e SPHINXOPTS="-Dlanguage='zh_CN'" html

可以直接打开生成的 _build\html\index.html 文件来查看。

代办列表#

待处理

EasyIDP之后可能会提供API来一次性加载某个文件夹下的所有txt文件作为一个 ROI 对象。

(原始条目 见 /home/docs/checkouts/readthedocs.org/user_builds/easyidp-zh-cn/checkouts/latest/docs/backgrounds/roi_marking.rst，第 173 行。)

待处理

shp文件仅仅能提供二维坐标，但是三维的地理空间坐标在后续的计算中也是很有用的。而DSM恰好可以提供高度值，因此整合两个文件到一起获取三维坐标是可行的。更详细的信息，可以参考欢迎查阅EasyIDP官方文档

(原始条目 见 /home/docs/checkouts/readthedocs.org/user_builds/easyidp-zh-cn/checkouts/latest/docs/backgrounds/roi_marking.rst，第 252 行。)

待处理

This API will be enhanced and changed in the future.

ignore (str) -> ignore_overflow (bool):

True: strickly in image area, default;
False: cut the polygon inside the image range;

(原始条目 见 /home/docs/checkouts/readthedocs.org/user_builds/easyidp-zh-cn/checkouts/latest/easyidp/reconstruct.py:docstring of easyidp.reconstruct.Sensor.in_img_boundary，第 11 行。)