Desarrollo

Trends.Earth es un software gratuito y de código abierto, licenciado bajo la Licencia Pública General GNU, versión 2.0 o posterior.

Hay una serie de componentes para las Trends.Earth herramienta. El primero es un complemento QGIS que admite el cálculo de indicadores, el acceso a datos sin procesar, informes y producción de mapas impresos. El código para el complemento, y más instrucciones sobre cómo instalarlo si desea modificar el código, están en trends.earth Depósito de GitHub.

El complemento de QGIS Trends.Earth es compatible con varios scripts Python diferentes que permiten el cálculo de varios indicadores en Google Earth Engine (GEE). Estas secuencias de comandos se encuentran en la subcarpeta «gee» de ese repositorio de GitHub. Los scripts GEE son compatibles con el módulo Python landdegradation, que incluye código para procesar entradas y salidas para el complemento, así como otras funciones comunes que admiten el cálculo de integrales NDVI, significado estadístico y otro código compartido. El código para este módulo está disponible en landdegradation repositorio en GitHub.

A continuación encontrará más detalles sobre cómo contribuir a Trends.Earth trabajando en el código del complemento, modificando el código de procesamiento o contribuyendo a traducir el sitio web y el complemento.

Modificación del código del complemento QGIS

Instalar dependencias

Python

El complemento está codificado en Python. Además de usarse para ejecutar el complemento a través de QGIS, Python también se usa para admitir la administración del complemento (cambiar la versión, instalar versiones de desarrollo, etc.). Aunque Python está incluido con QGIS, también necesitará una versión local de Python que pueda configurar con el software necesario para administrar el complemento. La forma más fácil de administrar múltiples versiones de Python es a través de la distribución Anaconda. Para trabajar desarrollando el complemento, se requiere Python 3. Para descargar Python 3.7 (recomendado) a través de Anaconda, vea esta página.

Dependencias de Python

Para trabajar con el código de tendencias.earth, debe tener Invoke instalado en su máquina, así como una serie de otros paquetes que se utilizan para administrar la documentación, las traducciones, etc. Estos paquetes se enumeran en el «dev» archivo de requisitos para Trends.Earth, por lo que se pueden instalar navegando en un símbolo del sistema a la raíz de la carpeta de códigos trend.earth y escribiendo:

pip install -r requirements-dev.txt

Nota

Si está utilizando Anaconda, primero querrá activar un entorno virtual Python 3.7 antes de ejecutar el comando anterior (y cualquiera de los otros comandos de invocación enumerados en la página). Una forma de hacerlo es iniciando un «Anaconda prompt», siguiendo las instrucciones en esta página de Anaconda <https://docs.anaconda.com/anaconda/user-guide/getting-started/#write-a-python-program-using-anaconda-prompt-or-terminal>`_.

PyQt

PyQt5 es el kit de herramientas gráficas utilizado por QGIS3. Para compilar la interfaz de usuario de Trends.Earth para QGIS3 necesita instalar PyQt5. Este paquete se puede instalar desde pip usando:

pip install PyQt5

Nota

PyQt4 es el kit de herramientas gráficas utilizado por QGIS2. La mejor fuente para este paquete en Windows es el conjunto de paquetes mantenido por Christoph Gohlke en UC Irvine. Para descargar PyQt4, seleccione el paquete apropiado de esta página. Elija el archivo apropiado para la versión de Python que está utilizando. Por ejemplo, si está utilizando Python 2.7, elija la versión con «cp27»; en el nombre del archivo. Si está utilizando Python 3.7, elija la versión con «cp37»; en el nombre del archivo. Elija «amd64»; para python de 64 bits y «win32»; para python de 32 bits.

Después de descargar desde el enlace anterior, use pip para instalarlo. Por ejemplo, para la rueda de 64 bits para Python 3.7, ejecutaría:

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

Cambiar la versión del complemento

La convención para Trends.Earth es que los números de versión que terminan en un número impar (por ejemplo, 0.65) son versiones de desarrollo, mientras que las versiones que terminan en un número par (por ejemplo (0.66) son versiones de lanzamiento. Las versiones de desarrollo del complemento nunca se lanzan a través de el repositorio QGIS, por lo que nunca son vistos por los usuarios normales del complemento. El equipo de desarrollo de Trends.Earth utiliza versiones de desarrollo con números impares mientras prueba nuevas características antes de su lanzamiento público.

Si desea realizar cambios en el código y ha descargado una versión pública del complemento (uno que termina en un número par), el primer paso es actualizar la versión del complemento al siguiente número impar secuencial. Entonces, por ejemplo, si descargó la versión 0.66 del complemento, necesitaría actualizar la versión para que sea 0.67 antes de comenzar a hacer sus cambios. Hay varios lugares en el código donde se menciona la versión (así como dentro de cada script GEE), por lo que hay una tarea de invocación para ayudar a cambiar la versión. Para cambiar la versión a 0.67, debe ejecutar:

invoke set-version -v 0.67

La ejecución del comando anterior actualizará el número de versión en cada lugar al que se hace referencia en el código. Para evitar confusiones, nunca cambie la versión a una que ya haya sido lanzada, siempre AUMENTE el valor de la etiqueta de versión al siguiente número impar.

Probar cambios en el complemento

Después de realizar cambios en el código del complemento, deberá probarlos para asegurarse de que el complemento se comporta como se esperaba y para asegurarse de que no surjan errores o errores. El complemento debe someterse a pruebas exhaustivas antes de ser lanzado al repositorio QGIS (donde otros usuarios pueden acceder a él) para garantizar que cualquier cambio en el código no rompa el complemento.

Para probar cualquier cambio que haya realizado en el complemento dentro de QGIS, deberá instalarlo localmente. Hay tareas de invocación que ayudan con este proceso. El primer paso antes de instalar el complemento es asegurarse de haber configurado el complemento con todas las dependencias que necesita para ejecutarse desde QGIS. Para hacer esto, ejecute:

invoke plugin-setup

La tarea anterior solo debe ejecutarse inmediatamente después de descargar el código de tendencias de la tierra, o si se realizan cambios en las dependencias del complemento. Por defecto, plugin-setup reutilizará cualquier archivo en caché en su máquina. Para comenzar desde cero, agregue el indicador -c (limpiar) al comando anterior.

Después de ejecutar plugin-setup, está listo para instalar el complemento en la carpeta de complementos QGIS en su máquina. Para hacer esto, ejecute:

invoke plugin-install

Después de ejecutar el comando anterior, tendrá que 1) reiniciar QGIS, o 2) utilizar el Plugin Reloader para recargar el «plugin» Trends.Earth con el fin de ver los efectos de los cambios que ha realizado.

Por defecto, plugin-install sobrescribirá cualquier archivo de complemento existente en su máquina, pero dejará en su lugar cualquier dato (límites administrativos, etc.) que el complemento podría haber descargado. Para comenzar desde cero, agregue el indicador -c (limpio) al comando anterior. Es posible que deba cerrar QGIS para realizar una instalación limpia del complemento utilizando el indicador -c.

Nota

De forma predeterminada, plugin-install supone que desea instalar el complemento que se utilizará en QGIS3. Para instalar el complemento para su uso en QGIS3, agregue el indicador -v 2 al comando plugin-install. Recuerde que el complemento puede o no ser completamente funcional en QGIS3: el complemento se diseñó originalmente para QGIS2 y todavía se está probando en QGIS3.

Sincronizar e implementar cambios en los binarios

Para acelerar los cálculos en Trends.Earth, algunas de las herramientas permiten utilizar binarios precompilados que se han compilado usando numba. Numba es un compilador de código abierto que puede compilar código Python y NumPy, haciéndolo más rápido que cuando se ejecuta como Python ordinario. Para evitar que los usuarios de Trends.Earth necesiten descargar Numba y todas sus dependencias, el equipo de Trends.Earth pone a disposición binarios precompilados para descargar si los usuarios eligen instalarlos.

Para generar binarios precompilados para el sistema operativo, el bitness (32/64 bit) y la versión de Python que está ejecutando en su máquina, use:

invoke binaries-compile

Nota

Necesitará un compilador de C ++ para que funcione el comando anterior. En Windows, vea esta página de github para obtener detalles sobre cómo instalar el compilador de Microsoft Visual C ++ necesario para su versión de Python. En MacOS, lo más probable es que necesites instalar Xcode. En Linux, instale la versión adecuada de GCC.

Para que los binarios estén disponibles públicamente, se distribuyen a través de un bucket de servicios web de Amazon S3. Para cargar los binarios generados con el comando anterior en el depósito, ejecute:

invoke binaries-sync

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

El comando anterior sincronizará cada archivo binario individual con S3. Sin embargo, los usuarios de la caja de herramientas descargan los archivos binarios como un único archivo zip vinculado a la versión del complemento que están utilizando. Para generar ese archivo zip para que los usuarios de Trends.Earth puedan acceder a él, ejecute:

invoke binaries-deploy

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

Crear un archivo ZIP de complemento

Hay varias tareas de invocación para ayudar a construir un archivo ZIP para implementar el complemento en el repositorio QGIS, o para compartir la versión de desarrollo del complemento con otros. Para empaquetar el complemento y todas sus dependencias en un archivo ZIP que se puede instalar siguiendo el proceso descrito en el archivo Léame de Trends.Earth, ejecutar:

invoke zipfile-build

Este comando creará una carpeta llamada build en la raíz de la carpeta de tendencias trend.earth, y en esa carpeta creará un archivo llamado LDMP.zip. Este archivo se puede compartir con otros, que pueden usarlo para instalar manualmente Trends.Earth. Esto puede ser útil si es necesario compartir las últimas funciones con alguien antes de que estén disponibles en la versión pública del complemento.

Implementación del archivo ZIP de la versión de desarrollo

La página Trends.Earth GitHub proporciona un enlace a un archivo ZIP que permite a los usuarios que no sean desarrolladores acceder a la versión de desarrollo de Trends.Earth. Para crear un archivo ZIP y ponerlo a disposición en esa página (el archivo ZIP se almacena en S3), ejecute:

invoke zipfile-deploy

Este comando empaquetará el complemento y lo copiará a https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip.

Nota

El comando anterior fallará si no tiene teclas que permitan el acceso de escritura al bucket trends.earth en S3.

Modificar el código de procesamiento de Earth Engine

Las secuencias de comandos de procesamiento de Google Earth Engine (GEE) utilizadas por Trends.Earth se almacenan en la carpeta «gee»; debajo de la carpeta Trends.earth principal. Para que este script sea accesible para los usuarios del plugin Trends.earth QGIS, deben implementarse en el servicio api.trends.earth que Conservation International mantiene para permitir a los usuarios del plugin usar Earth Engine sin la necesidad de saber cómo programar o tener cuentas de usuario individuales en GEE. A continuación se describe cómo probar e implementar scripts GEE para usar con Trends.Earth.

Configurar dependencias

docker

El paquete trends.earth-CLI requiere docker para funcionar. Siga estas instrucciones para instalar Docker en Windows y` estas instrucciones para instalar Docker en Mac OS <https://docs.docker.com/docker-for-mac/install/>`_. Si está ejecutando Linux, siga las instrucciones en esta página que son apropiados para la distribución de Linux que está utilizando.

Probar un script de Earth Engine localmente

Después de instalar el paquete trends.earth-CLI, deberá configurar un archivo .tecli.yml con un token de acceso a una cuenta de servicio GEE para probar los scripts en GEE. Para configurar la cuenta de servicio GEE para tecli, primero obtenga la clave para su cuenta de servicio en formato JSON (de la consola de Google Cloud), luego codifíquela en base64. Proporcione esa clave codificada en base64 a tecli con el siguiente comando:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

donde «key» es la llave de la cuenta de servicio de formato JSON codificada en base64.

Al convertir un script que especifica el código que se ejecutará en GEE de JavaScript a Python, o al realizar modificaciones en ese código, puede ser útil probar el script localmente, sin implementarlo en el servidor api.trends.earth. Para hacer esto, use la tarea de invocación ejecutar. Por ejemplo, para probar el script «land_cover», vaya al directorio raíz del código Trends.Earth y, en un símbolo del sistema, ejecute:

invoke tecli-run land_cover

Esto usará el paquete trends.earth-CLI para construir y ejecutar un contenedor acoplable que intentará ejecutar el script &quot;land_cover&quot;. Si hay errores de sintaxis en el script, estos aparecerán cuando se ejecute el contenedor. Antes de enviar un nuevo script a api.trends.earth, asegúrese siempre de que invoke tecli-run pueda ejecutar el script sin ningún error.

Al usar invoke tecli-run, puede recibir un error que dice:

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.

Este error puede ser causado si el reloj en el contenedor docker no está sincronizado con el reloj del sistema. Reiniciar Docker debería corregir este error.

Edición de plantillas de capas vectoriales

Trends.Earth permite a los usuarios digitalizar nuevas características vectoriales para delinear áreas de interés especial.

Por ahora sólo se soportan las capas «falso positivo/negativo», pero se pueden añadir más si es necesario. Cualquier capa vectorial se crea a partir de los archivos de plantilla GeoPackage, que se encuentran dentro de la carpeta «data/error_recode» del directorio de instalación del complemento o extensión. Para cada tipo de vector hay seis archivos de plantilla, uno por cada idioma oficial de la ONU. El código de idioma ISO se añade como sufijo al nombre del archivo. Esto es necesario para proporcionar etiquetas localizadas en los formularios de atributos. Cuando se solicite la creación de la capa vectorial, QGIS buscará el archivo de plantilla teniendo en cuenta la configuración regional del propio QGIS; como opción alternativa se utilizará la versión inglesa del archivo de plantilla.

Para cambiar el esquema de la capa es necesario cambiar los archivos de plantilla correspondientes en la carpeta «data/error_recode» del directorio de instalación del complemento o extensión. También el archivo de plantilla contiene una configuración de estilo y atributos por defecto que se aplicará automáticamente a la capa cuando se cargue en QGIS.

Para mostrar las listas en forma de atributos se utiliza un «widget» QML incorporado. Los datos para las listas se almacenan en la tabla de atributos de la capa vectorial. Los valores de los campos correspondientes se extraen con la ayuda de expresiones.

El código para generar las listas tiene el siguiente aspecto:

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\"")] }
    }
}

To extract field value function expression.evaluate("\"prod_deg\"") is used, the only argument it accepts is the name of the field. For false positive/negative layers chart contains three indicators: productivity, land cover and soil organic carbon. For each indicator plugin keeps three values stable, degraded and improved percentage of the polygon area. For example, in case of productivity indicator fields will be:

  • prod_deg: productividad degradada

  • prod_stab: productividad estable

  • prod_imp: productividad mejorada

El mismo enfoque de la nomenclatura se aplica a la cobertura del suelo (land_* fields) y al carbono orgánico del suelo (soil_* fields).

El cálculo del porcentaje de área se realiza con una función de expresión personalizada, su código se puede encontrar en el archivo charts.py en el directorio raíz del «plugin». La función está optimizada para trabajar con polígonos grandes y utiliza el siguiente flujo de trabajo. Para una geometría dada, encontrar un bbox y extraer susbset ráster usando este bbox. Efectúar la rasterización de la geometría en memoria y aplicar como una máscara al ráster. A continuación, se cuenta el número de píxeles que tienen un valor específico y se calcula el porcentaje. Puesto que el recuento de píxeles se basa en funciones de matriz de numpy, es muy rápido incluso para grandes polígonos.

En el primer intento de editar una capa vectorial, el usuario se encontrará con un diálogo en el que deberá seleccionar los conjuntos de datos que se utilizarán para los indicadores. A continuación, el «plugin» configurará valores de expresión por defecto para todos los campos de los indicadores, de modo que el valor se actualizará en cada cambio de geometría.

Gestión de los metadatos de los conjuntos de datos

Los metadatos del conjunto de datos se almacenan en el formato QMD de QGIS. Estos archivos QMD pueden crearse para cada trama individualmente y también para todo el conjunto de datos. El diálogo del editor de metadatos se abre desde el menú Editar metadatos en el «dock» de Trends.Earth.

Cuando el conjunto de datos se exporta a ZIP, la conversión a ISO XML se realiza mediante una transformación XLST. Las transformaciones correspondientes se encuentran en el subdirectorio data\xsl de la carpeta de instalación del «plugin».

Actualización del marco de información

Resumen del marco de información

El marco de trabajo de los informes está diseñado para ser extensible mientras que también proporciona interactividad al usuario a través de operaciones no bloqueantes. El marco se apoya en las clases QgsProject y QgsPrintLayout que no son seguras para los hilos, de ahí el uso de qgis_process para hacer el trabajo pesado de generar informes (y listas). Puede encontrar más información sobre qgis_process aquí.

Hay dos pasos principales que la caja de herramientas realiza al generar informes /y listas) para las capas por defecto de un trabajo:

  1. Crea un objeto ReportTaskContext que compone un objeto ReportConfiguration (ver Configuración de los parámetros del informe) y un objeto Job que se representa en el panel Datasets. Este objeto ReportTaskContext se convierte en un archivo JSON y luego se pasa como uno de los argumentos de un objeto ReportProcessHandlerTask (que hereda de QgsTask).

  2. El objeto ReportProcessHandlerTask inicia una instancia separada de qgis_process y pasa la ruta del archivo JSON como una entrada al algoritmo de procesamiento trendsearth:reporttask. Se trata de una fina envoltura que deserializa el archivo al objeto ReportTaskContext y lo pasa a un objeto ReportTaskProcessor que es responsable de generar los informes y el trabajo del proyecto QGIS. Para algoritmos que requieren listas, el objeto ReportTaskProcessor pasa el objeto de un trabajo a uno AlgorithmChartsManager que comprueba si hay una configuración de lista definida para el algoritmo del trabajo. Si está definida, genera las listas correspondientes como archivos PNG. (Veáse Añadir configuraciones de listas para más información sobre las configuraciones de listas)

El siguiente diagrama ilustra a grandes rasgos este proceso:

../_images/report_dev_process.png

* Clique en la imagen para hacerla más grande.

Nota

Algunos de los nombres de las funciones en el diagrama anterior se han simplificado con fines ilustrativos. Las clases mencionadas se encuentran en los módulos LDMP.reports y ``LDMP.processing_provider.report <https://github.com/ConservationInternational/trends.earth/tree/master/LDMP/processing_provider/report.py>`_.

Añadir variables de diseño del informe

Las variables del informe proporcionan información de contexto relacionada con un trabajo, capa (o banda) o Informes durante el proceso de ejecución del informe. Actualmente, la caja de herramientas admite las variables enumeradas en la sección Variables de expresión del diseño.

Cada variable se define como un namedtuple en el módulo LDMP.reports.expressions y, seguidamente, es actualizada y evaluada por el objeto ReportTaskProcessor.

Siga las siguientes pautas sobre cómo añadir nuevas variables de trabajo o de capa actual.

Variable de trabajo

Permite añadir información sobre el trabajo actual (que se está ejecutando) a un diseño de informe. La información sobre cada variable de trabajo se encapsula en un objeto :code:ˋJobAttrVarifo` que se compone de cuatro atributos:

Nombre del atributo

Descripción

Tipo de datos

Valor por defecto

job_attr

El nombre del atributo de un objeto Job utilizado en una notación de puntos. Por ejemplo, id corresponde a job.id. Incluso se puede utilizar la notación de puntos para referirse a los atributos en las clases anidadas internas, p. ej., results.uri.uri.

Cadena

N/A

var_name

Nombre de la variable de diseño del informe. Debe llevar el prefijo te_job_.

Cadena

N/A

default_value

Un valor por defecto para nombre_de_var, que se aplica sobre todo al crear diseños.

objeto

objeto

fmt_func

Un objeto de función que se utilizará para convertir el valor del atributo del trabajo a un formato que sea compatible con las expresiones QGIS. Por ejemplo, str puede utilizarse para convertir el valor del id del trabajo de UUID a una cadena. Aquí también se pueden utilizar funciones lambda.

objeto de la función

Ninguno

El fragmento de código siguiente muestra cómo añadir una variable te_job_result_name que corresponde a job.results.name.

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

Capa variable

Ofrece información sobre la actual capa ráster que está siendo ejecutada. Esta información variable se encapsula en un objeto LayerVarInfo que está compuesto por tres atributos:

Nombre del atributo

Descripción

Tipo de datos

Valor por defecto

var_name

El nombre de la variable de diseño del informe. Debe llevar el prefijo te_current_layer_.

Cadena

N/A

default_value

Un valor por defecto para nombre_de_var, que se aplica sobre todo al crear diseños.

objeto

objeto

fmt_func

Un objeto de función que se utilizará para extraer o convertir un valor de un objeto QgsRasterLayer a un formato que sea compatible con expresiones QGIS. También puede utilizar funciones lambda aquí.

Por ejemplo, lambda layer: layer.name() devuelve el nombre de la capa.

objeto de la función

Ninguno

El fragmento de código siguiente muestra cómo añadir una variable te_current_layer_height que corresponde a la altura de la capa del ráster.

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

Nota

Estas variables están únicamente disponibles en el marco del diseño.

Añadir configuraciones de listas

Las listas se pueden agrupar usando un objeto de configuración de lista que corresponde a un algoritmo específico. La definición de una nueva configuración de lista es un proceso de tres pasos:

  1. Crear una nueva clase de lista que herede de BaseChart en el módulo LDMP.reports.charts. Implementar la función export para especificar el tipo de lista, propiedades, etc. usando la biblioteca de Python Plotly que viene con QGIS. Finalmente, dentro de de la función export, hay que llamar a la función save_image para escribir el objeto Figure de Plotly como un archivo de imagen utilizando cualquiera de los formatos soportados por la clase QImageWriter de Qt. También se puede especificar la ruta como relativa al directorio raíz de salida, el cual está disponible como un atributo en la clase base. Veáse el siguiente fragmento de código:

    # 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

    Puede consultar la clase UniqueValuesPieChart para ver un ejemplo más completo.

  2. Crear una clase de configuración de lista que herede de BaseAlgorithmChartsConfiguration e implemente la función BaseAlgorithmChartsConfiguration. La clase de configuración de lista básicamente define qué listas se utilizarán para un algoritmo determinado. El atributo layer_band_infos es una lista de objetos LayerBandInfo que contiene los datos de capa y band_info necesarios para producir las listas. Puede consultar la clase LandCoverChartsConfiguration para ver un ejemplo más completo.

  3. Por último, asigne un algoritmo (nombre) a la clase de configuración de la lista correspondiente en la clase AlgorithmChartsManager tal y como se muestra a continuación:

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

    La clase AlgorithmChartsManager, que se instancia en el objeto ReportTaskProcessor, creará un nuevo objeto de configuración de listas para el algoritmo de un trabajo correspondiente cuando se creen informes.

Contribuyendo a la documentación

Visión general

La documentación para Trends.Earth se produce usando Sphinx, y está escrito en` reStructuredText <http://docutils.sourceforge.net/rst.html>`_ formato. Si no está familiarizado con ninguna de estas herramientas, consulte su documentación para obtener más información sobre cómo se utilizan.

La documentación de Trends.Earth se almacena en la carpeta &quot;docs&quot; en el directorio principal de trends.earth. Dentro de esa carpeta hay una serie de archivos y carpetas clave a tener en cuenta:

  • build: contiene la documentación de construcción de trends.earth (en formato PDF y HTML). Tenga en cuenta que solo aparecerá en su máquina después de ejecutar la tarea de invocación docs-build.

  • i18n: contiene traducciones de la documentación a otros idiomas. Los archivos aquí normalmente se procesan automáticamente mediante tareas de invocación, por lo que nunca debería tener motivos para modificar nada en esta carpeta.

  • recursos: contiene todos los recursos (principalmente imágenes o PDF) a los que se hace referencia en la documentación. Actualmente solo hay una carpeta («EN», para inglés) ya que todas las imágenes en la documentación son de la versión en inglés del complemento, si se pueden agregar carpetas adicionales apropiadas en «recursos»; con códigos de idioma de dos letras para incluir imágenes específicas de un idioma en particular.

  • fuente: contiene los archivos fuente reStructuredText que definen la documentación (estos son el texto real en inglés de la documentación y son los archivos que es más probable que necesite modificar).

Instalar dependencias

Dependencias de Python

Para trabajar con la documentación, debe tener invoke, Sphinx, sphinx-intl y sphinx-rtd-theme (el tema para el sitio web Trends.Earth) instalado en su máquina. Todos estos paquetes se enumeran en el archivo de requisitos &quot;dev&quot; para Trends.Earth, por lo que se pueden instalar navegando en un símbolo del sistema a la raíz de la carpeta de códigos de tendencias.earth y escribiendo:

pip install -r requirements-dev.txt

LaTeX

LaTeX se utiliza para producir salidas en PDF de la documentación para Trends.Earth.

Para instalar en Windows, siga el proceso descrito aquí para instalar la distribución proTeXt de LaTeX desde` el archivo zip disponible aquí <http://ftp.math.purdue.edu/mirrors/ctan.org/systems/windows/protext/>`_. El instalador de LaTeX es bastante grande (varios GB), por lo que puede llevar un tiempo descargarlo e instalarlo.

En MacOS, MacTeX es una buena opción y se puede instalar siguiendo las instrucciones aquí.

En Linux, la instalación de LaTeX debería ser mucho más fácil: use el administrador de paquetes de su distribución para encontrar e instalar cualquier distribución de LaTeX que se incluya por defecto.

Qt Linguist

Qt Linguist también es necesario para extraer cadenas del código y la GUI para la traducción. El comando «lrelease» debe estar disponible y en su camino. Intenta probar:

lrelease

dentro de una ventana de terminal. Si no se encuentra el archivo, deberá instalar Qt Linguist. Esta página es una fuente de instaladores para Qt Linguist. Una vez que instale Qt Linguist, asegúrese de agregar la carpeta que contiene lrelease a su ruta para que el script de invocación Trends.Earth pueda encontrarla.

Actualización y construcción de la documentación.

Una vez que haya instalado los requisitos de sphinx, estará listo para comenzar a modificar la documentación. Los archivos a modificar se encuentran en la carpeta «docs\source»;. Después de realizar cualquier cambio en estos archivos, deberá compilar la documentación para ver los resultados. Existen dos versiones de la documentación de Trends.Earth: una versión HTML (utilizada para el sitio web) y una versión PDF (para descargar sin conexión). Para compilar la documentación de Trends.Earth, use la tarea de invocación &quot;docs-build&quot;. De forma predeterminada, esta tarea generará la documentación completa para Trends.Earth, en HTML y PDF, para todos los idiomas admitidos. Esto puede tardar un tiempo en ejecutarse (hasta unas pocas horas). Si solo está probando los resultados de algunos cambios menores en la documentación, generalmente es mejor usar la opción -f (para «rápido»). Esta opción construirá solo la documentación HTML en inglés, que debería tomar solo unos segundos. Para construir usando la opción rápida, ejecute:

invoke docs-build -f

El comando anterior tardará unos segundos en ejecutarse, y luego si busca en «docs\build\html\en», verá la versión HTML de la documentación. Cargue el archivo «index.html» en un navegador web para ver cómo se ve.

Para compilar la documentación completa, para todos los idiomas, en PDF y en HTML (recuerde que esto puede tardar algunas horas en completarse), ejecute:

invoke docs-build

Después de ejecutar el comando anterior, verá (para inglés) la documentación HTML en «docs\build\html\en», y los PDF de la documentación en «docs\build\html\en\pdfs».

Si desea probar un idioma específico (al probar traducciones, por ejemplo), puede especificar un código de idioma de dos letras para crear solo los documentos para ese idioma. Por ejemplo, para construir solo la documentación en español, ejecute:

invoke docs-build -l es

Tenga en cuenta que las opciones se pueden combinar, por lo que puede usar la opción rápida para crear solo la versión HTML de la documentación en español ejecutando:

invoke docs-build -f -l es

Al compilar la documentación completa para el sitio web, es una buena idea eliminar primero las compilaciones antiguas de la documentación, ya que pueden contener archivos que ya no se usan en la documentación actualizada. Para hacer esto, use la opción -c (limpiar):

invoke docs-build -c

En general, docs-build DEBE completarse sin ningún error si planea compartir la documentación o publicarla en el sitio web. Sin embargo, al probar cosas localmente, es posible que desee ignorar los errores de documentación que aparecen solo para algunos de los idiomas (debido a errores de sintaxis que surgen de errores de traducción, etc.) y continuar construyendo la documentación restante independientemente de si hay algún error . Para hacer esto, use la opción -i (ignorar errores):

invoke docs-build -i

Siempre que realice cambios en el texto de la documentación, es una buena idea enviar las últimas cadenas a Transifex para que puedan traducirse. Para actualizar las cadenas en Transifex con cualquier cambio nuevo, ejecute:

invoke translate-push

Nota

Para ejecutar con éxito el comando anterior, necesitará tener la clave para la cuenta Transifex de Trends.Earth.

Documentación de construcción para lanzamiento

Antes de lanzar nueva documentación, siempre obtenga las últimas traducciones de Transifex para que todas las traducciones estén actualizadas. Para hacer esto, ejecute:

invoke translate-pull

Para compilar una versión de la documentación para publicación pública (ya sea en el sitio web o en PDF), debe compilar toda la documentación utilizando docs-build sin parámetros adicionales:

invoke docs-build

Este proceso debe completarse con éxito sin errores. Si se produce algún error durante el proceso, revise el mensaje de error y realice las modificaciones necesarias para permitir que la compilación se complete con éxito. Una vez que la compilación se completa sin errores, los archivos están listos para implementarse en el sitio web.

Nota

Los dos comandos anteriores también tienen opciones -f (forzar) que fuerzan a tirar o empujar las últimas traducciones desde o hacia Transifex (respectivamente). Solo use estas opciones si está MUY seguro de lo que está haciendo, ya que pueden sobrescribir completamente las traducciones en Transifex, lo que lleva a la pérdida del trabajo realizado por los traductores si las últimas traducciones aún no se han comprometido con github.

Agregar nuevo texto de documentación

Todos los archivos .rst nuevos que se agreguen a la documentación deben agregarse a varios archivos de configuración para asegurarse de que aparezcan en el menú de navegación, que estén traducidos correctamente y (para tutoriales) que se generen en PDF para que puedan ser descargado para su uso sin conexión.

  • docs\source\index.rst: agregue nuevos archivos .rst en el lugar apropiado aquí para asegurarse de que estén vinculados desde el menú de navegación.

  • .tx\config: enumere los nuevos archivos .rst aquí (en el mismo formato que los otros archivos ya incluidos) para que el software de traducción los conozca y pueda traducirlos

  • docs\source\conf.py: si desea generar un archivo PDF de la página del sitio web, debe incluir esa página aquí en la lista latex_documents. Por lo general, hacemos esto solo para las páginas de tutoriales que queremos poner a disposición de los participantes del taller en archivos PDF individuales. Cada página del sitio se incluirá en la versión PDF del sitio web en su conjunto, independientemente de si está en la lista de documentos de latex.

Agregar nuevas imágenes u otros recursos

Cualquier nueva imagen u otro recurso (PDF, etc.) que necesite la documentación debe agregarse en «docs\resources\en». Si lo desea, es posible cargar diferentes versiones de una imagen para que la imagen aparezca con las traducciones adecuadas. Esto podría ser útil si desea mostrar la interfaz GUI en el idioma apropiado, por ejemplo. para hacer esto, primero suba una copia de la imagen a «docs\resources\en» (con texto en inglés). Luego, cree una copia de la imagen con el texto traducido y colóquela en la carpeta correspondiente a ese idioma (por ejemplo, una imagen que muestre traducciones al español iría en «docs\resources\es»). La versión en inglés de la imagen se utilizará como predeterminada para todos los idiomas para los que no se proporciona una versión nativa de la imagen, mientras que se utilizará una versión localizada cuando esté disponible.

Nota

Hay otra carpeta, docs\\source\\static, que se usa para contener recursos temporalmente mientras se ejecutan los scripts que compilan la documentación de Trends.Earth. Es posible que tenga imágenes en esa carpeta si alguna vez ha creado la documentación en esa máquina. Esta carpeta nunca debe usarse para agregar nuevos recursos - los nuevos recursos siempre deben ir bajo docs\\resources\\en o, para las imágenes traducidas, la carpeta específica del idioma correspondiente bajo docs\\recursos.

Contribuyendo como traductor

Transifex gestiona las traducciones para el complemento QGIS y también para este sitio. Si desea contribuir a traducir el complemento y la documentación (¡y nos encantaría contar con su ayuda!), Puede solicitar unirse a nuestro equipo a través de transifex, o enviándonos un correo electrónico a trends.earth@conservation.org.