Разработка

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

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

Плагин Trends.Earth для QGIS поддерживается рядом различных скриптов на Python, позволяющих рассчитывать различные показатели в Google Earth Engine (gee). Эти скрипты находятся в подпапке gee соответствующего репозитория GitHub.

Этот плагин также поддерживается рядом других модулей:

  • Модуль «trends.earth-algorithms» включает код для обработки входных и выходных данных для плагина, а также другие общие функции, поддерживающие вычисление интегралов NDVI, статистическую значимость и другой общий код. Код этого модуля доступен в репозитории «landdegradation <https://github.com/ConservationInternational/trends.earth-algorithms>» на GitHub.

  • Модуль trends.earth-schemas содержит код для управления схемами, используемыми для ввода/вывода данных из trends.earth, включая обработку классов землепользования, параметров заданий, структурирование отчетов для Конвенции ООН о ликвидации всех форм дискриминации и другие связанные функции.

Ниже приведена более подробная информация о том, как внести свой вклад в Trends.Earth, работая над кодом графического интерфейса плагина, изменяя код обработки или участвуя в переводе веб-сайта и плагина.

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

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

Python

Плагин написан на Python. Помимо запуска плагина через QGIS, Python также используется для поддержки управления плагином (изменение версии, установка версий для разработчиков и т. д.). Хотя Python входит в состав QGIS, вам также потребуется локальная версия Python, которую вы сможете установить с программным обеспечением, необходимым для управления плагином. Самый простой способ управлять несколькими версиями Python — это использовать дистрибутив Anaconda <https://www.anaconda.com>. Для работы над разработкой плагина требуется Python 3. Чтобы загрузить Python 3.7 (рекомендуется) через Anaconda, см. эту страницу <https://www.anaconda.com/distribution/#download-section>.

Зависимости 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.

Обновление списка кэшированных границ.

После обновления набора данных geoBoundaries обновите кэшированный список, входящий в состав плагина, выполнив следующую команду:

invoke download-boundaries-cache

Задача выполняет аутентификацию через API Trends.Earth. Для настройки учетных данных добавьте файл invoke.yaml` в корневой каталог репозитория со следующими записями:

trends_earth_api:
    user: "you@example.com"
    password: "your-password"

Вы также можете указать учетные данные с помощью переменных среды TRENDS_EARTH_API_USER и TRENDS_EARTH_API_PASSWORD перед запуском задачи.

Построение файла 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 разрабатываемой версии

На странице Trends.Earth в GitHub есть ссылка на ZIP-файл, который позволяет пользователям, не являющимся разработчиками, получить доступ к разрабатываемой версии Trends.Earth. Чтобы создать ZIP-файл и разместить его на этой странице (ZIP-файл хранится в S3), выполните следующую команду:

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 позволяет пользователям оцифровывать новые векторные объекты для выделения областей, представляющих особый интерес.

В настоящее время поддерживаются только слои с «ложными положительными/отрицательными» значениями, но при необходимости можно добавить и другие. Любой векторный слой создается из шаблонных файлов GeoPackage, которые находятся в папке data/error_recode в каталоге установки плагина. Для каждого типа векторных данных существует 6 шаблонных файлов, по одному для каждого официального языка ООН. Код языка ISO добавляется в качестве суффикса к имени файла. Это необходимо для предоставления локализованных меток в формах атрибутов. При запросе на создание векторного слоя QGIS будет искать шаблонный файл, учитывая локаль QGIS, а в качестве резервного варианта будет использоваться английская версия шаблонного файла.

Для изменения схемы слоя необходимо изменить соответствующие файлы шаблонов в папке data/error_recode каталога установки плагина. Файл шаблона также содержит встроенную конфигурацию стилей и атрибутов по умолчанию, которая будет автоматически применена к слою при загрузке в 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).

Расчет процентного соотношения площади выполняется с помощью пользовательской функции выражения, код которой можно найти в файле charts.py в корневом каталоге плагина. Функция оптимизирована для работы с большими полигонами и использует следующий алгоритм. Для заданной геометрии найдите ограничивающий прямоугольник (bbox) и извлеките подмножество растра, используя этот прямоугольник. Выполните растеризацию геометрии в памяти и примените ее в качестве маски к растру. Затем подсчитайте количество пикселей, имеющих определенное значение, и рассчитайте процентное соотношение. Поскольку подсчет пикселей основан на функциях массивов numpy, он очень быстр даже для больших полигонов.

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

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

Метаданные набора данных хранятся в формате 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»). Английская версия изображения будет использована по умолчанию для всех языков, для которых нет изображения с переводом, тогда как при наличии локализованной версии, будет использована она.

Примечание

Существует ещё одна папка, docs\source\static, которая используется для временного хранения ресурсов во время выполнения скриптов, создающих документацию Trends.Earth. Если вы когда-либо создавали документацию на этом компьютере, в этой папке могут отображаться изображения. Эту папку никогда не следует использовать для добавления новых ресурсов — новые ресурсы всегда следует размещать в папке docs\resources\en или, для переведённых изображений, в соответствующей папке для конкретного языка в docs\resources.

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

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

Выпуск новой версии плагина

Обзор

Выпуск новой версии Trends.Earth включает в себя обновление номеров версий, создание git-тегов, сборку пакета плагина и его публикацию как на GitHub, так и в репозитории плагинов QGIS. Этот процесс упрощается благодаря задачам вызова, которые автоматизируют большинство этих шагов.

Рабочий процесс выпуска

Для создания нового публичного релиза выполните следующие действия:

1. Обновите журнал изменений

Сначала обновите список изменений в файле LDMPmetadata.txt, указав подробную информацию об изменениях в этой версии. Включите номер версии и дату выпуска, а затем пункты, описывающие новые функции, исправления ошибок и другие изменения.

2. Установите номер версии

Запустите задачу set-version, чтобы обновить номера версий во всей базе кода:

invoke set-version -v X.Y.Z -m

Где XYZ — это новый номер версии (например, 2.1.20). Флаг -m гарантирует, что номера версий также будут обновлены в зависимых модулях (trends.earth-schemas и trends.earth-algorithms).

Эта команда:

  • Обновит `LDMP/metadata.txt новой версией

  • Сгенерирует файл LDMP/_version.py с информацией из git.

  • Обновит версию в документации (docs/source/conf.py)

  • Установит флаг experimental в зависимости от четности/нечетности номеров версий (четные = стабильная версия, нечетные = версия для разработки).

  • Обновит ссылки на зависимости в файлах требований

Примечание

Для стабильных релизов (с четными номерами версий, например, 2.1.18) задача set-version обновит ссылки на зависимости, чтобы использовать версии с тегами. Для релизов для разработчиков (с нечетными номерами версий, например, 2.1.19) она будет использовать ветку master.

**3. Обновите скрипты GEE (если уместно) **

Если вы внесли изменения в скрипты Google earth Engine (в папке gee) или в файлы trends.earth-schemas или trends.earth-algorithms, добавьте флаг -g при выполнении команды set-version:

invoke set-version -v X.Y.Z -m -g

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

# In trends.earth-schemas (where x.y.z is the new version number
invoke set-tag -v x.y.z

# In trends.earth-algorithms (where x.y.z is the new version number)
invoke set-tag -v x.y.z

После того, как обе зависимости будут помечены тегами, опубликуйте обновленные скрипты на API-сервере Trends.Earth:

invoke tecli-publish

Эта команда загружает все скрипты GEE на api.trends.earth, чтобы они стали доступны пользователям плагина. Для успешного выполнения этой команды необходимы права администратора.

4. Подтвердите все изменения

Убедитесь, что все измененные файлы зафиксированы в git:

git add -A
git commit -m "Release version X.Y.Z"

5. Создайте и отправьте git-теги

После фиксации изменений в этом репозитории выполните команду `invoke set-tag:

invoke set-tag -v x.y.z # (where x.y.z is the new version number

Это создаст аннотированный git-тег для плагина (например, v2.1.20) и отправит его в GitHub. Если у вас есть незафиксированные изменения, задача предложит вам сначала их зафиксировать.

6. Создайте релиз на GitHub

Запустите задачу release-GitHub, чтобы создать релиз на GitHub с прикрепленным zip-файлом плагина:

invoke release-github

Эта команда:

  • Создайте чистый zip-архив плагина (например, LDMP_2.1.20.zip) со всеми зависимостями.

  • Удалите все файлы с расширением .pyc, чтобы соответствовать требованиям безопасности репозитория QGIS.

  • Создайте релиз на GitHub, прикрепив к нему ZIP-архив плагина в качестве загружаемого ресурса

Примечание

Для корректной работы этой команды вам потребуется персональный токен доступа GitHub с областью действия repo, настроенный в файле invoke.yaml. Инструкции по созданию токена см. в сообщениях об ошибках, возникающих при сбое аутентификации.

7. Опубликуйте в репозиторий QGIS

Наконец, вручную загрузите плагин в репозиторий плагинов QGIS:

  1. Загрузите zip-файл плагина (например, LDMP_2.1.20.zip) из созданного вами релиза на GitHub (он будет указан в разделе ssets.

  2. Войдите в QGIS plugin repository <https://plugins.qgis.org/plugins/>

  3. Перейдите на страницу управления плагинами

  4. Загрузите новую версию, используя zip-файл

Репозиторий QGIS проверит zip-файл и предоставит к нему доступ пользователям через менеджер плагинов QGIS.

Соглашения о нумерации версий

В Trends.Earth используются следующие правила нумерации версий:

  • Чётные числа (например, 2.1.18, 2.1.20): стабильные версии, предназначенные для публичного использования

  • Нечётные номера (например, 2.1.19, 2.1.21): релизы для тестирования новых функций

Версии для разработчиков никогда не публикуются в репозитории QGIS и используются только командой разработчиков для тестирования.