貢献する#
コード提供#
続きはこちら
バグ報告#
続きはこちら
ドキュメント作成#
The main documentation documentation is written in reStructuredText and generated by sphinx. Hosted publishing by ReadTheDocs platform.
Documentation has been built on Windows 11 (developing) and Linux (ReadTheDocs platform). Building documentation on macOS may also be possible due to the python cross-platform features but it is not officially tested.
注釈
If you find any typo errors in the official documentation, it is very welcome that you make a pull request to fix it (Fork -> clone -> search in your code editor -> fix -> preview generated html -> pull request).
前提条件#
You need to install python dependices by the following code (please activate your virtual environment first):
(venv)> pip install -r requirements/docs.txt
In order to deal with jupyter notebook extensions, you will also need to install pandoc into your computer.
Check by below to ensure successfully installed:
(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()
Build#
After cloning the EasyIDP repository, activate the virtual environment, first enter the docs
folder:
(venv) EasyIDP> cd docs
(venv) EasyIDP/docs>
そうすれば、次のようにドキュメントを構築することができます。
(venv) EasyIDP/docs> make html
You can open the _build\html\index.html
to see the generated documentations
翻訳#
Here we using the sphinx-intl
to provide services for multi-language documentation. If you want to contribute to your native lanuage translation, please following the instruction or the offical document
1. extract translatable messages#
First, extract document’s translatable messages into pot files:
(venv) EasyIDP/docs> make gettext
This invokes the sphinx gettext builder that generates *.pot
files under _build/gettext
directory.
注意
Please check the outputs carefully, to see if any warnings or errors exists. Do not run the following code until they are fixed and disappared.
2. prepare translation files#
Then, using the following code to convert previous broken sentencs to correspoinding lanuage folder ( _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
注釈
The last part -l zh_CN -l ja
means translate to Chinese (zh_CN) and Japanese (ja), if you need add another translation languages. Feel tree to add -l xxx
in the end, and you can refer your lanuage code xxx
from here
Tip
If you want to add the lanuage document published on the readthedocs
, please translate at your local first, then make a pull request to our repo (just docs\locale\<your-lang>\LC_MESSAGES
folder), when it pass our review, we will open the link for that lanuage as soon as possible.
3. translate#
This is the most time-consuming step. Please pay attention carefully about which files are changed. Then check the folder _locale\<your-lang>\LC_MESSAGES
, and edit those changed files.
Tip
The *.po
files have the following formats:
#: ../../contribute.rst:5
msgid "Contribute"
msgstr ""
The first line is where it appears, the second line is the original sentence, while the last line is the translation you need to type in.
Sometims, it will appear with line of #, fuzzy
:
#: ../../contribute.rst:5
#, fuzzy
msgid "Contribute"
msgstr ""
It means the origianl sentence have been changed, please edit the translation again.
Please do the following things:
Check which files have changed in the previous outputs. And for each file
Press
Ctrl
+F
in your text editor to find out if any#, fuzzy
exists, change these sentences first.Find if any
msgstr ""
exists. You don't have to translate everything, for those words/sentence don't need to translate (e.g. EasyIDP, Python), just leave them blank.
注釈
If the sentence is too long, feel free to connect the sentence by adding "" in an new line:
msgstr "This sentence is too long"
"But it is okay to continue like this"
"and this ..."
But should not have a blank line!
注意
For the inline code and links, please ensure they are wrapped by spaces:
OK -> Press ``Ctrl`` + `url <url>`_ in your
ERR -> Press``Ctrl``+ `url <url>`_in your
Otherwise this sentences will get error without notification, and the translation will not appear.
4. render and preview#
Lastly, change the language of local preview ( -Dlanguage='your_lang'
), and render the document pages:
(venv) EasyIDP/docs> set SPHINXOPTS=-Dlanguage=zh_CN
(venv) EasyIDP/docs> make html
(venv) EasyIDP/docs> make -e SPHINXOPTS="-Dlanguage='zh_CN'" html
You can open the _build\html\index.html
to see the generated documentations.
Todoリスト#
課題
In the future, EasyIDP may provide an API to load all txt files in one folder as ROI
object directly.
(元のエントリ は、 /home/docs/checkouts/readthedocs.org/user_builds/easyidp-japanese/checkouts/latest/docs/backgrounds/roi_marking.rst の 173 行目です)
課題
The shp file only provides 2D coordinates, while 3D geography coordinates is needed for further calculation. The DSM can provides the height value. And the 3D coordinates can be obtained by combining shp and DSM file together. For more details about this, please refer to EasyIDPのドキュメントへようこそ!
(元のエントリ は、 /home/docs/checkouts/readthedocs.org/user_builds/easyidp-japanese/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-japanese/checkouts/latest/easyidp/reconstruct.py:docstring of easyidp.reconstruct.Sensor.in_img_boundary の 11 行目です)