Разработка

Trends.Earth — это бесплатное и открытое программное обеспечение, лицензированное Универсальной общественной лицензией GNU, версия 2.0 или более поздней.

Инструмент Trends.Earth состоит из ряда компонентов. Первый — это плагин QGIS, поддерживающий расчет индикаторов, доступ к сырым данным, отчетности и производству печатных карт. Код для плагина и дальнейшие инструкции по его установке, если вы хотите модифицировать код, находятся в репозитории GitHub trends.earth.

The Trends.Earth QGIS plugin is supported by a number of different Python scripts that allow calculation of the various indicators on Google Earth Engine (GEE). These scripts sit in the «gee» sub-folder of that GitHub repository.

The plugin is also supported by a number of other modules:

  • The trends.earth-algorithms module includes code for processing inputs and outputs for the plugin, as well as other common functions supporting calculation of NDVI integrals, statistical significance, and other shared code. The code for this module is available in the landdegradation repository on GitHub.

  • The trends.earth-schemas module includes code for managing the schemas used for data input/output from trends.earth, including handling land cover classes, job parameters, structuring reports for UNCCD, and other related functions

Further details are below on how to contribute to Trends.Earth by working on the plugin GUI code, by modifying the processing code, or by contributing to translation of the website and plugin.

Модификация кода плагина QGIS

Установка зависимостей

Python

The plugin is coded in Python. In addition to being used to run the plugin through QGIS, Python is also used to support managing the plugin (changing the version, installing development versions, etc.). Though Python is included with QGIS, you will also need a local version of Python that you can setup with the software needed to manage the plugin. The easiest way to manage multiple versions of Python is through the Anaconda distribution. For work developing the plugin, Python 3 is required. To download Python 3.7 (recommended) through Anaconda, see this page.

Зависимости Python

Чтобы работать с кодом trends.earth, вам необходимо, чтобы на вашем компьютере был установлен Invoke, а также ряд других пакетов, которые используются для управления документацией, переводами и т.д. Все эти пакеты перечислены в файле требований «dev» для Trends.Earth, так что их можно установить, пройдя в командной строке в корневой каталог папке кода trends.earth и набрав:

pip install -r requirements-dev.txt

Примечание

Если вы используете Anaconda, вы сначала захотите установить виртуальную среду Python 3.7, прежде чем запустить указанную выше команду (и любые из других invoke-команд, перечисленных на странице). Один из способов сделать это — запустить «командную строку Anaconda», следуя инструкциям на этой странице Anaconda.

PyQt

PyQt5 — это набор графических инструментов, используемых QGIS3. Чтобы собрать пользовательский интерфейс для Trends.Earth для QGIS3, вам необходимо установить PyQt5. Пакет можно установить из pip, используя:

pip install PyQt5

Примечание

PyQt4 — это набор графических инструментов, используемых QGIS2. Лучший ресурс для этого пакета на Windows — из набора пакетов, поддерживаемых Кристофером Гольке на UC Irvine. Чтобы скачать PyQt4, выберите подходящий пакет с этой страницы. Выберите подходящий файл для той версии Python, которую вы используете. Например, если вы используете Python 2.7, выберите версию «cp27» в названии файла. Если вы используете Python 3.7, выберите версию с «cp37» в названии файла. Выберите «amd64» для python 64-bit и «win32» для python 32-bit.

После скачивания по приведенной выше ссылке используйте «pip», чтобы установить его. Например, для колеса 64-bit для Python 3.7 вы запустите:

pip install PyQt4-4.11.4-cp37-cp37m-win_amd64.whl

Изменение версии плагина

Согласно договоренности, в Trend.Earth номера версий, которые заканчиваются нечетным числом (например, 0.65), это разрабатываемые версии, тогда как версии, которые заканчиваются четным числом (например, 0.66), это выпускные версии. Разрабатываемые версии плагина никогда не выпускаются через репозиторий QGIS, поэтому обычные пользователи плагина их никогда не видят. Разрабатываемые версии, заканчивающиеся на нечетное число, используются командой разработчиков Trend.Earth во время испытаний новых функций до их публичного выпуска.

Если вы желаете внести изменения в код и скачали публичный выпуск плагина (тот, который заканчивается четным числом), первый шаг — это обновить версию плагина до следующего за ним последовательного нечетного числа. Так, например, если вы скачали версию 0.66 плагина, вам понадобится обновить версию до 0.67, прежде чем вы начнете вносить свои изменения. В коде есть несколько мест, где упоминается версия (также, как и внутри каждого скрипта GEE), поэтому есть invoke-задача, которая помогает с изменением версии. Чтобы изменить эту версию до 0.67, вы запустите:

invoke set-version -v 0.67

Запуск приведенной выше команды обновит номер версии в каждом месте, где он упоминается в этом коде. Чтобы избежать путаницы, никогда не меняйте версию на ту, что уже была выпущена, а всегда УВЕЛИЧИВАЙТЕ значение метки версии на следующее нечетное число.

Испытание изменений в плагине

После внесения изменений в код плагина вам потребуется протестировать их, чтобы убедиться в том, что плагин ведет себя согласно ожиданий и что не возникнет никаких багов или ошибок. Плагин должен пройти исчерпывающие испытания, прежде чем будет выпущен в репозиторий QGIS (где его могут оценивать другие пользователи), чтобы убедиться, что никакие изменения кода не ломают плагин.

Чтобы протестировать любые изменения, которые вы внесли в плагин внутри QGIS, вам понадобится установить его локально. Есть invoke-задачи, которые помогают с этим процессом. Первый шаг, предшествующий установке плагина, это убедиться, что вы оснастили плагин всеми зависимостями, которые ему нужны для запуска из QGIS. Чтобы это сделать, запустите:

invoke plugin-setup

Приведенная выше задача должна быть выполнена сразу же после скачивания кода trends.earth, или если в зависимости для плагина были внесены какие-либо изменения. По умолчанию «плагин-настройка» будет использовать любые кешированные файлы на вашем компьютере. Чтобы начать с нуля, добавьте флажок «-с» (чисто) к приведенной выше команде.

После запуска «плагина-установки» вы готовы к установке плагина в папку плагинов QGIS на вашем компьютере. Чтобы сделать это, запустите:

invoke plugin-install

После запуска приведенной выше команды вам понадобится либо: 1) перезапустить QGIS, или 2) использовать Перезагрузчик плагина чтобы перезагрузить плагин Trends.Earth и посмотреть последствия внесенных вами изменений.

По умолчанию «плагин-установка» запишется сверху любых существующих файлов на вашем компьютере, но не тронет никаких данных (административные границы и т.д.), которые этот плагин мог скачать. Чтобы начать все сначала, добавьте флажок «-c» (чисто) к приведенной выше команде. Возможно, вам понадобиться закрыть QGIS, чтобы успешно выполнить чистую установку плагина, используя флажок «-с».

Примечание

По умолчанию плагин-установка предполагает, что вы хотите установить плагин для использования в QGIS3. Чтобы установить плагин для использования в QGIS3, добавьте флажок «-v 2» в команду «плагин-установка». Помните, что плагин может быть, а может и не быть полностью функциональным на QGIS3 — этот плагин был изначально разработан для QGIS2 и все еще тестируется на QGIS3.

Синхронизация и внедрение изменений в двоичные файлы

Чтобы ускорить вычисления в Trends.Earth, некоторые из инструментов позволяют использовать предварительно скомпилированные двоичные файлы, которые были скомпилированы с использованием numba. Numba — это открытый компилятор, который может компилитровать код Python и NumPy, делая это быстрее, чем когда он запущен как обычный Python. Чтобы пользователям Trends.Earth не потребовалось скачивать Numba и все из его зависимостей, команда Trends.Earth делает предварительно скомпилированные двоичные файлы доступными для скачивания, если пользователи выбирают их установить.

Чтобы сгенерировать предварительно скомпилированные двоичные файлы для OS битностью 32/64 бита и версии Python, которая используется на вашем компьютере, используйте:

invoke binaries-compile

Примечание

You will need a C++ compiler for the above command to work. On Windows, see this github page for details on how to install the Microsoft Visual C++ compiler needed for your Python version. On MacOS, you will most likely need to install Xcode. On Linux, install the appropriate version of GCC.

Чтобы сделать эти двоичные файлы публично доступными, их распространяют через бакет S3 сервисов Amazon Web. Чтобы загрузить в бакет эти двоичные файлы, сгенерированные приведенной выше командой, запустите:

invoke binaries-sync

Примечание

Приведенная выше команда не сработает, если у вас нет ключей, дающих право доступа в бакет «trends.earth» на S3.

Указанная выше команда синхронизирует каждый индивидуальный двоичный файл с S3. Однако пользователи инструментария скачивают двоичные файлы как один файл zip, привязанный к версии плагина, которые они используют. Для того чтобы сгенерировать этот файл zip, чтобы пользователи Trends.Earth могли его оценить, запустите:

invoke binaries-deploy

Примечание

Приведенная выше команда не сработает, если у вас нет ключей, дающих право доступа в бакет «trends.earth» на S3.

Построение файла ZIP плагина

Есть несколько invoke-задач, которые помогают построить файл ZIP, для того чтобы внедрить плагин в репозиторий QGIS или поделиться разрабатываемой версией плагина с другими. Чтобы заархивировать плагин и все его зависимости в файл ZIP, который можно установить, придерживаясь „процедуры, описанной в файле readme <https://github.com/ConservationInternational/trends.earth#installing-latest-packaged-development-version>`_, запустите:

invoke zipfile-build

Эта команда создаст папку под именем «построить» в корневом каталоге папки кода trends.earth, и в этой папке она создаст файл «LDMP.zip». Этим файлом можно делиться с другими, которые могут использовать его для ручной установки Trends.Earth. Это может быть полезно, если есть необходимость поделиться с кем-то самыми свежими функциями, прежде чем они станут доступными в публично выпущенной версии плагина.

Внедрение файла ZIP разрабатываемой версии

The Trends.Earth GitHub page gives a link to a ZIP file that allows users who may not be developers to access the development version of Trends.Earth. To create a ZIP file and make it available on that page (the ZIP file is stored on S3), run:

invoke zipfile-deploy

Эта команда заархивирует плагин и скопирует его в https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip.

Примечание

Приведенная выше команда не сработает, если у вас нет ключей, дающих право доступа в бакет «trends.earth» на S3.

Модификация кода обработки Earth Engine

Все скрипты обработки Google Earth Engine (GEE), используемые Trends.Earth, сберегаются в папке «gee» под главной папкой trends.earth. Чтобы эти скрипты были доступны пользователям плагина trends.earth QGIS, они должны быть внедрены в сервис api.trends.earth, поддерживаемый Международным обществом сохранения природы, чтобы позволить пользователям плагина использовать Earth Engine без необходимости уметь программировать или иметь индивидуальные пользовательские учетные записи на GEE. Ниже описано, как протестировать и внедрить скрипты GEE, которые будут использоваться с Trends.Earth.

Настройка зависимостей

докер

Пакету trends.earth-CLI для работы требуется docker Следуйте этим инструкциям для установки докера в Windows, и этим инструкциям для установки докера в Mac OS. Если вы пользуетесь Linux, следуйте инструкциям на этой странице , для дистрибутива Linux, который вы используете.

Локальное тестирование скрипта Earth Engine

После установки пакета trends.earth-CLI вам нужно настроить файл .tecli.yml с токеном доступа к учётной записи службы GEE для тестирования скриптов в GEE. Для настройки учётной записи службы GEE для tecli, сначала получите ключ для своей учётной записи службы в формате JSON (из google cloud console), потом закодируйте в base64. Введите этот закодированный в base64 ключ в tecli с помощью следующей команды:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

где «ключ» — ключ учётной записи службы, закодированный в base64, в формате JSON.

При преобразовании кода, определяющего скрипт для запуска в GEE из JavaScript в Python, может быть полезно провести локальное тестирование скрипта без развертывания его на сервере api.trends.earth. Чтобы это сделать, используйте задачу вызова run. Например, чтобы тестировать скрипт «land_cover», перейдите в корневой каталог кода Trends.Earth и в командной строке выполните:

invoke tecli-run land_cover

Будет использован пакет trends.earth-CLI для создания и выполнения докерного контейнера, который попытается выполнить скрипт «land_cover». Если в скрипте есть синтаксические ошибки, они будут видны при выполнении контейнера. Перед вводом нового скрипта в api.trends.earth убедитесь, что invoke tecli-run может выполнять скрипты без ошибок.

При использовании invoke tecli-run может возникать ошибка с текстом:

Invalid JWT: Token must be a short-lived token (60 minutes) and in a
reasonable timeframe. Check your iat and exp values and use a clock with
skew to account for clock differences between systems.

Эта ошибка может возникать, если часы на докером контейнере не синхронизированы с часами системы. Перезапуск докера должен исправить эту ошибку.

Редактирование шаблонов векторных слоёв

Trends.Earth allows users to digitize new vector features to delineate areas of special interest.

For now only «false positive/negative» layers are supported, but more can be added if necessary. Any vector layer is created from the template GeoPackage files, which can be found inside the data/error_recode folder of the plugin installation directory. For each vector type there are 6 template files, one for each UN official language. The ISO language code is added as a suffix to the file name. This is necessary to provide localized labels in the attribute forms. When creation of the vector layer is requested QGIS will look for the template file taking QGIS locale into account, as a fall-back option English version of the template file is used.

To change schema of the layer it is necessary to change corresponding template files in the data/error_recode folder of the plugin installation directory. Also template file contains a built-in default styling and attribute form configuration which will be automatically applied to the layer when loading into QGIS.

Для отображения диаграмм в форме атрибута используется встроенный виджет QML. Данные диаграммы хранятся в диаграмме атрибутов векторного слоя. Величины из соответствующих полей извлекаются с помощью выражения.

Код для генерирования диаграмм выглядит как:

import QtQuick 2.0
import QtCharts 2.0

ChartView {
    width: 380
    height:200
    margins {top: 0; bottom: 0; left: 0; right: 0}
    backgroundColor: "#eeeeec"
    legend.alignment: Qt.AlignBottom
    antialiasing: true
    ValueAxis {
        id: valueAxisY
        min: 0
        max: 100
    }

    BarSeries {
        id: mySeries
        axisY: valueAxisY
        axisX: BarCategoryAxis { categories: ["Productivity", "Land cover", "Soil organic carbon"] }
        BarSet { label: "Degraded"; color: "#9b2779"; values: [expression.evaluate("\"prod_deg\""), expression.evaluate("\"land_deg\""), expression.evaluate("\"soil_deg\"")] }
        BarSet { label: "Improved"; color: "#006500"; values: [expression.evaluate("\"prod_imp\""), expression.evaluate("\"land_imp\""), expression.evaluate("\"soil_imp\"")] }
        BarSet { label: "Stable"; color: "#ffffe0"; values: [expression.evaluate("\"prod_stab\""), expression.evaluate("\"land_stab\""), expression.evaluate("\"soil_stab\"")] }
    }
}

Для извлечения значения поля используется функция``expression.evaluate(»"prod_deg"»)``, единственный аргумент, который она принимает при этом — имя поля. В диаграмме слоёв ложного срабатывания/несрабатывания есть три индикатора: продуктивность, земляной покров и почвенный органический углерод. Для каждого индикатора плагин сохраняет три величины: процент устойчивого, ухудшенного и улучшенного состояния полигональной области. Например, в случае, когда поля индикатора продуктивности будут:

  • prod_deg — ухудшенная продуктивность

  • prod_stab — устойчивая продуктивность

  • prod_imp — улучшенная продуктивность

Такой же подход при присваивании имён применяется к земляному покрову (land_* fields) и почвенному органическому углероду (soil_* fields).

Calculation of area percentage is done with custom expression function, its code can be found in the file charts.py in the plugin root directory. Function optimized to work with large polygons and uses following workflow. For a given geometry find a bbox and extract raster subset using this bbox. Perform in-memory geometry rasterization and apply it as a mask to raster. Then count number of pixels which have specific value and calculate percentage. As pixel counting is built on numpy array functions it is very fast even for big polygons.

При первой попытке редактировать векторный слой пользователю представляется диалог, в котором нужно выбрать, какие наборы данных использовать для индикаторов. Затем плагин создаст величины выражения по умолчанию для всех полей индикатора, и величина будет обновляться при каждом изменении геометрии.

Работа с метаданными набора данных

Метаданные набора данных хранятся в формате QGIS QMD. Эти файлы QMD могут быть созданы для каждого растра индивидуально и также для целого набора данных. Диалог редактирования метаданных открывается из меню Edit metadata в Trends.Earth dock.

Когда набор данных экспортируется в ZIP, преобразование в ISO XML выполняется с использованием трансформации XSLT. Соответствующая трансформация расположена в поддиректории data\xsl в папке установки плагина.

Актуализация системы отчётности

Обзор системы отчётности

Система отчётности создана как расширяемая и интерактивная для пользователей через неблокирующие операции. Система в значительной степени использует классы QgsProject и QgsPrintLayout, которые не являются поточно-ориентированными, поэтому используются qgis_process для тяжёлой работы генерирования отчётов (и диаграмм). Больше информации о qgis_process здесь.

Есть два основных этапа действия набора инструментов при создании отчётов и диаграмм для слоёв задачи по умолчанию:

  1. Создаётся объект ReportTaskContext, включающий объект ReportConfiguration (см. Настройка параметров отчета) и объект Job, представленный в панели Datasets. Этот объект ReportTaskContext сериализуется в файл формата JSON, а потом переносится как один из аргументов в объект ReportProcessHandlerTask (который наследует от QgsTask).

  2. Объект ReportProcessHandlerTask инициирует отдельные экземпляры qgis_process и передает маршрут файлу формата JSON как вклад в алгоритм процесса trendsearth:reporttask. Это тонкая обёртка, которая десериализирует файл в объект ReportTaskContext и передает его в объект ReportTaskProcessor, отвечающий за создание отчётов и проект QGIS. Для алгоритмов, требующих диаграмм, объект ReportTaskProcessor передает объект-задание объекту AlgorithmChartsManager, который проверяет наличие заданной конфигурации диаграммы для алгоритма задачи. Если она определена, создается соответствующая диаграмма в виде файлов PNG. (Смотрите более подробно о конфигурациях диаграмм Добавление конфигурации диаграммы)

На диаграмме ниже этот процесс проиллюстрирован подробно:

* Для увеличения масштаба, нажмите на изображение.

Примечание

Некоторые из названий функций на диаграмме выше были упрощены для удобства иллюстрации. Упомянутые классы можно найти в модулях LDMP.reports и LDMP.processing_provider.report.

Добавление переменных макета отчёта

Переменные отчёта предоставляют контекстную информацию, связанную с задачей, слоем (или лентой) или Отчеты в процессе выполнения отчёта. В данный момент инструментарий поддерживает переменные, перечисленные в разделе Переменные выражения макета.

Каждая переменная определена как namedtuple в модуле LDMP.reports.expressions и, следовательно, обновляется и оценивается с помощью объекта ReportTaskProcessor.

Чтобы добавить новую задачу или переменные актуального слоя, следуйте инструкциям ниже.

Переменная задачи

Позволяет добавлять в макет отчёта информацию об актуальной задаче, которая выполняется. Информация о каждой переменной задачи инкапсулируется в объекте JobAttrVarInfo, который состоит из четырех атрибутов:

Название атрибута

Описание

Тип данных

Величина по умолчанию

job_attr

Присваивайте название объекту Job, как оно используется в точечном представлении. Например, id соответствует job.id. Вы даже можете использовать точечное представление, обращаясь к атрибутам во внутренних вложенных классах, например, results.uri.uri.

Строка

Н.п.

var_name

Название переменной макета отчёта. Должно содержать префикс te_job_.

Строка

Н.п.

default_value

Величина по умолчанию, которую следует использовать для var_name, преимущественно применяется при разработке макетов.

объект

объект

fmt_func

Объект-функция, которая будет использована для преобразования величины атрибута задачи в формат, совместимый с выражениями QGIS. Например, str можно использовать для преобразования величины id задачи из UUID в строку. Также вы можете использовать здесь лямбда-функции.

объект-функция

Нет

Фрагмент кода ниже показывает, как добавить перемененную te_job_result_name, которая соответствует job.results.name.

# LDMP/reports/expressions.py
def _job_attr_var_mapping() -> typing.List[JobAttrVarInfo]:
    return [
        ...
        JobAttrVarInfo('results.name', 'te_job_result_name', '', str),
        ...
    ]

Переменная слоя

Предоставляет информацию об актуальном выполняемом слое растра. Информация этой переменной инкапсулирована в объекте LayerVarInfo, включающем три атрибута:

Название атрибута

Описание

Тип данных

Величина по умолчанию

var_name

Название переменной макета отчёта. Должно содержать префикс te_current_layer_.

Строка

Н.п.

default_value

Величина по умолчанию, которую следует использовать для var_name, преимущественно применяется при разработке макетов.

объект

объект

fmt_func

Объект-функция, которая будет использована для извлечения и/или преобразования величины из QgsRasterLayer object в формат, совместимый с выражениями QGIS. Здесь вы тоже можете использовать лямба-функции.

Например, lambda layer: layer.name() возвращает имя слоя.

объект-функция

Нет

Фрагмент кода ниже показывает, как добавить перемененную te_current_layer_height, которая соответствует высоте слоя растра.

# LDMP/reports/expressions.py
def _current_job_layer_var_mapping() -> typing.List[LayerVarInfo]:
    return [
        ...
        LayerVarInfo(
            'te_current_layer_height',
            '',
            lambda layer: layer.height()
        )
        ...
    ]

Примечание

Эти переменные доступны только в области макета.

Добавление конфигурации диаграммы

Диаграммы могут быть сгруппированы с использованием объекта конфигурации диаграммы, соответствующего определённому алгоритму. Определение конфигурации новой диаграммы — трёхступенчатый процесс:

  1. Создать новый класс диаграмм, наследующий из BaseChart в модуле LDMP.reports.charts . Применение функции export для определения типа и свойств диаграмм, с использованием библиотеки Python Plotly, которая поставляется в составе QGIS. Наконец, в функции export назовите функцию save_image для записи Figure объекта Plotly в качестве файла изображения, используя любой из форматов, поддерживаемых классом Qt QImageWriter. Вы можете также указать маршрут по отношению к выходному каталогу корня, который также доступен в качестве атрибута в основном классе. Смотрите фрагмент кода ниже:

    # LDMP/reports/charts.py
Class MyCustomChart(BaseChart):
    def export(self) -> typing.Tuple[bool, list]:
        status = True
        messages = []

        # Create chart Figure using Plotly and set properties
        fig = go.Figure(...)

        # Add warning or error messages
        messages.append('Colour list not supported.')

        # Set image path in dataset's reports folder
        img_path = f'{self.root_output_dir}/chart-NDVI.png'

        # Save image and append its path
        self.save_image(fig, img_path)
        self._paths.append(img_path)

        return status, messages

    Для более полного примера обратитесь к классу UniqueValuesPieChart.

  2. Создать класс конфигурации диаграммы, наследующий из BaseAlgorithmChartsConfiguration и применить функцию _add_charts. Этот класс конфигурации диаграмм в основном определяет, какие диаграммы будут использованы для данного алгоритма. Атрибут layer_band_infos является списком объектов LayerBandInfo, содержащим информацию о слое и ленте, необходимую для производства диаграмм. Для более полного примера обратитесь к классу LandCoverChartsConfiguration.

  3. Наконец, добавить алгоритм (имя) соответствующего класса конфигурации диаграммы в класс AlgorithmChartsManager, как показано ниже:

    # LDMP/reports/charts.py
Class AlgorithmChartsManager:
    def _set_default_chart_config_types(self):
        ...
        self.add_alg_chart_config('land-cover', LandCoverChartsConfiguration)
        self.add_alg_chart_config('productivity', MyCustomLandProductivityChartsConfiguration)
        ...

    Класс AlgorithmChartsManager, инстанцированный в объект ReportTaskProcessor, создаст новый объект конфигурации диаграммы для соответствующего алгоритма задачи во время генерирования отчётов.

Участие в создании документации

Обзор

Документация Trends.Earth производится с использованием Sphinx, записывается в формате reStructuredText. Если вы незнакомы с каким-то из этих инструментов, ознакомьтесь с их документацией, чтобы узнать об их использовании.

Документация Trends.Earth хранится в папке «docs» folder в основном каталоге trends.earth. Внутри этой папки есть несколько ключевых файлов и папок, требующих внимания:

  • build: содержит документацию build для trends.earth (в формате PDF и HTML). Она появится на вашем устройстве только после выполнения задачи вызова docs-build.

  • i18n: содержит переводы документации на другие языки. Эти файлы обычно обрабатываются автоматически с использованием задач вызова, поэтому у вас не должно быть причин для изменений содержания этой папки.

  • resources: содержит любые ресурсы (в основном изображения и PDF), относящиеся к документации. В настоящий момент есть только одна папка («EN» для английского), так как все изображения в документации взяты из английской версии плагина — при необходимости дополнительные папки могут быть добавлены в «ресурсы» с двухбуквенными кодами языка, чтобы включить изображения, связанные с определенным языком.

  • source: содержит файлы исходного кода reStructuredText, определяющие документацию (актуальный текст на английском языке и файлы, которые с большой вероятностью требуют изменения).

Установка зависимостей

Зависимости Python

Для работы с этой документацией следует вызвать Sphinx, sphinx-intl и sphinx-rtd-theme (тема вебсайта Trends.Earth), установленные на вашем устройстве. Эти пакеты перечислены в файле требований «dev» для Trends.Earth, то есть, они могут быть установлены путем выполнения навигации в командной строке к корню папки trends.earth code при вводе:

pip install -r requirements-dev.txt

LaTeX

LaTeX используется для производства вывода документации Trends.Earth в формате PDF.

Чтобы установить в Windows, следуйте этим инструкциям для установки LaTeX из дистрибутива proTeXt из файла `zip, доступного здесь<http://ftp.math.purdue.edu/mirrors/ctan.org/systems/windows/protext/>`_. Установщик LaTeX довольно большой (несколько Гб), поэтому загрузка и установка может потребовать времени.

Для MacOS, MacTeX — хороший вариант, может быть установлен при выполнении этих инструкций.

В Linux установка LaTeX должна быть гораздо проще — используйте менеджер пакета дистрибутива для выяснения и установки включенного по умолчанию дистрибутива LaTeX.

Qt Linguist

Qt Linguist также требуется для формирования строк на основе кода и GUI для перевода. Команда «lrelease» должна быть доступна и включена в ваш маршрут. Попробуйте:

lrelease

в окне терминала. Если файл не обнаружен, необходимо установить Qt Linguist. Эта страница один источник установщиков для Qt Linguist. После установки Qt Linguist необходимо добавить папку, содержащую команду lrelease в маршрут, так чтобы скрипт вызова Trends.Earth мог её найти.

Актуализация и формирование документации

После установки требований sphinx вы готовы начать модификацию документации. Требующие модификации файлы находятся в папке «docs\source». После внесения изменения в эти файлы вам понадобится сформировать документацию, чтобы увидеть результаты. Есть две версии документации Trends.Earth: HTML-версия (используется для сайта) и PDF-версия (для загрузки на устройство). Для формирования документации Trends.Earth используйте задачу вызова «docs-build». По умолчанию эта задача сформирует полную документацию для Trends.Earth, в HTML и PDF, для всех поддерживаемых языков. Это может занять некоторое время (до нескольких часов). Если вы только тестируете результаты некоторых малых изменений в документации, лучше всего использовать опцию -f (для «fast/быстро»). Это действие сформирует только документацию в формате HTML на английском языке и займёт всего несколько секунд. Для формирования в быстром режиме воспользуйтесь:

invoke docs-build -f

Выполнение команды выше займёт несколько секунд, если вы посмотрите по адресу «docs\build\html\en», вы увидите HTML-версию документации. Загрузите файл «index.html» в веб-браузере, чтобы увидеть, как он выглядит.

Для формирования полной документации для всех языков в форматах PDF и HTML (помните, что выполнение этого может занять несколько часов), выполните:

invoke docs-build

После выполнения вышеупомянутой команды вы увидите документацию на английском языке в формате HTML по адресу «docs\build\html\en», а в формате PDF по адресу «docs\build\html\en\pdfs».

Если вы хотите протестировать конкретный язык (при тестировании перевода, например), вы можете указать две буквы кода языка для того, чтобы сформировать документы только для этого языка. Например, для формирования документации только на испанском, выполните:

invoke docs-build -l es

Опции можно комбинировать, то есть, можно использовать быстрый вариант для формирования HTML-версии документации на испанском языке, выполняя:

invoke docs-build -f -l es

Формируя полную документацию для сайта, полезно первоначально удалить старые версии документации, так как они могут содержать файлы, более не актуальные для обновленной документации. Чтобы это сделать, используйте опцию -c (clean/очистить):

invoke docs-build -c

В общем, команда docs-build ДОЛЖНА быть выполнена без ошибок, если вы планируете поделиться документацией или разместить её на сайте. Однако при локальном тестировании вам может быть удобно проигнорировать ошибки документации, которые появляются только для некоторых языков (например, из-за синтаксических ошибок, связанных с ошибками перевода), и продолжить формирование оставшейся документации, несмотря на наличие и отсутствие ошибок. Чтобы это сделать, воспользуйтесь опцией -i (ignore errors / игнорировать ошибки):

invoke docs-build -i

При внесении изменений в текст документации будет полезно направить последние строки в Transifex, чтобы они могли быть переведены. Для обновления строк в Transifex с изменениями, выполните:

invoke translate-push

Примечание

Чтобы успешно выполнить упомянутую выше команду, нужно иметь ключ к учетной записи Trends.Earth Transifex.

Формирование окончательной документации

Перед созданием новой документации всегда используйте последние версии перевода из Transifex, чтобы все переводы были актуальными. Для этого выполните:

invoke translate-pull

Для формирования версии документации для общего просмотра (на сайте или в формате PDF), нужно сгенерировать всю документацию, используя команду docs-build без дополнительных параметров:

invoke docs-build

Этот процесс должен быть выполнен успешно без ошибок. Если в процессе возникают ошибки, рассмотрите сообщения об ошибках и внесите необходимые изменения, чтобы сформировать версию успешно. После окончания формирования без ошибок все файлы готовы для размещения на сайте.

Примечание

Обе из команд выше имеют также опции -f (force/сила), которые принудительно выводят или вводят последние переводы из или в Transifex (соответственно). Используйте эти опции только если вы АБСОЛЮТНО уверены в том, что вы делаете, так как они могут полностью переписать переводы в Transifex, что приведет к утрате работы, сделанной переводчиками, если последние переводы еще не были утверждены в github.

Добавление нового текста документации

Любые новые файлы .rst, добавленные в документацию, должны быть добавлены к файлам нескольких конфигураций, для того, чтобы они появились в меню навигации, были нужным образом переведены и, в случае учебников, чтобы они формировались в формате PDF-файлов, которые можно загрузить на устройство.

  • docs\source\index.rst: добавляйте файлы .rst в нужное место здесь, чтобы они были связаны с меню навигации.

  • .tx\config: вносите новые файлы .rst здесь (в таком же формате, как и уже включенные файлы), чтобы уведомить программу перевода об их наличии и необходимости обработки

  • docs\source\conf.py: если вы хотите сгенерировать PDF-файл страницы сайта, вы должны внести эту страницу в список latex_documents. Обычно мы делаем это только для страниц учебников, которые мы хотим сделать доступными участникам семинара в виде отдельных PDF-файлов. Каждая страница на этом сайте будет включена в PDF-версию на сайте в целом, независимо от того, включена ли она в список latex_documents.

Добавление новых изображений или других ресурсов

Любые новые изображения или другие ресурсы (PDF и другие), которые необходимы документации, должны быть добавлены по адресу «docs\resources\en». При желании можно загрузить разные версии изображения, чтобы изображение появилось с необходимым переводом. Это может быть полезно, если вы хотите, чтобы интерфейс GUI отображался на нужном языке, например. Для этого сначала загрузите копию изображения к «docs\resourcesen» (с текстом на английском языке). После создайте копию изображения с переведенным текстом и разместите это изображение в папку нужного языка (например, изображение, показывающее перевод на испанский, должно находиться по адресу «docs\resources\es»). Английская версия изображения будет использована по умолчанию для всех языков, для которых нет изображения с переводом, тогда как при наличии локализованной версии, будет использована она.

Примечание

There is another folder, docs\\source\\static, that is used to hold resources temporarily while running the scripts that build the Trends.Earth documentation. You may have images listed under that folder if you have ever built the documentation on that machine. This folder should never be used to add new resources - new resources should always go under docs\\resources\\en or, for translated images, the appropriate language-specific folder under docs\\resources.

Участие в качестве переводчика

Переводы для плагина QGIS и этого сайта управляются transifex. Если вы хотите принять участие в переводе плагина и документации (мы будем рады вашей помощи!), вы можете отправить запрос на присоединение к нашей команде через transifex, или написав нам по адресу trends.earth@conservation.org.

Releasing a new plugin version

There are several steps to making a new public release of the plugin:

  • Update changelog in LDMPmetadata.txt

  • Run invoke set-version -v X.Y.Z -m (where X.Y.Z is the new version) to set the new version number for both trends.earth and subcomponents (trends.earth-schemas and trends.earth-algorithms)

  • Ensure all changes are commited, and then tag the new versions and push those tags to github by running invoke set-tag -m

  • Ensure that all new versions and tags are pushed to github

  • Publish release on QGIS repository

  • Publish on github with - Run invoke release-github

Примечание

If you want to make a release after updating the scripts that call the Trends.Earth API (so if either the code under the gee folder changes, or if trends.earth-schemas or trends.earth-algorithms have changed, then you need to add a -g flag to the above command. After running invoke set-version with the -g flag you will also need to run invoke tecli-publish, in order to push the updated scripts to the API.