Contribute#

Code contribution#

To be continued

Bug reports#

To be continued

Documentation#

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.

Note

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).

Prerequisites#

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>

Then you can build the documentation by:

(venv) EasyIDP/docs> make html

You can open the _build\html\index.html to see the generated documentations

Translation#

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.

Caution

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

Note

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:

  1. Check which files have changed in the previous outputs. And for each file

  2. Press Ctrl + F in your text editor to find out if any #, fuzzy exists, change these sentences first.

  3. 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.

Note

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!

Caution

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 lists#

Todo

In the future, EasyIDP may provide an API to load all txt files in one folder as ROI object directly.

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/easyidp/checkouts/latest/docs/backgrounds/roi_marking.rst, line 173.)

Todo

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 Welcome to EasyIDP’s documentation!

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/easyidp/checkouts/latest/docs/backgrounds/roi_marking.rst, line 252.)

Todo

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;

back2raw_ignore_todo.png'

(The original entry is located in /home/docs/checkouts/readthedocs.org/user_builds/easyidp/checkouts/latest/easyidp/reconstruct.py:docstring of easyidp.reconstruct.Sensor.in_img_boundary, line 11.)