Desenvolvimento

Trends.Earth é um software livre e de código aberto, licenciado sob a GNU General Public License, version 2.0 or later.

Há vários componentes na ferramenta Trends.Earth. O primeiro é um plugin QGIS que suporta cálculos de indicadores, acesso a dados brutos, relatórios e produção de mapas impressos. O código para o plugin e mais instruções sobre como instalá-lo, se você deseja modificar o código, estão em trends.earth Repositório no GitHub.

O plugin do QGIS Trends.Earth é suportado por diversos scripts de Python que permitem o cálculo dos vários indicadores no Google Earth Engine (GEE). Estes scripts encontram-se na subpasta «gee» desse repositório do GitHub.

O plugin é também suportado por uma série de outros módulos:

  • O módulo trends.earth-algorithms inclui o código para o processamento de entradas e saídas do plugin, bem como outras funções comuns que suportam o cálculo de integrais de NDVI, significância estatística e outro código partilhado. O código deste módulo está disponível no repositório landdegradation no GitHub.

  • O módulo trends.earth-schemas inclui o código para gerir os esquemas utilizados na entrada e saída de dados do trends.earth, incluindo a gestão de classes de ocupação do solo, parâmetros de tarefas, estruturação de relatórios para a UNCCD e outras funções relacionadas

Apresentam-se abaixo mais detalhes sobre como contribuir para o Trends.Earth, trabalhando no código da interface gráfica do plugin, modificando o código de processamento ou contribuindo para a tradução do website e do plugin.

Modificando o código QGIS Plugin

Instalando dependências

Python

O plugin é codificado em Python. Além de ser utilizado para correr o plugin através do QGIS, o Python é também usado para apoiar a gestão do mesmo (alterar a versão, instalar versões de desenvolvimento, etc.). Embora o Python esteja incluído no QGIS, necessitará também de uma versão local do Python que possa configurar com o software necessário para gerir o plugin. A forma mais fácil de gerir múltiplas versões de Python é através da distribuição Anaconda. Para trabalhos de desenvolvimento do plugin, é necessário o Python 3. Para descarregar o Python 3.7 (recomendado) através do Anaconda, consulte esta página <https://www.anaconda.com/distribution/#download-section>.

Dependências do Python

Para trabalhar com o código trends.earth, é necessário ter o Invoke instalado em sua máquina, além de vários outros pacotes usados para gerenciar a documentação, traduções, etc. Esses pacotes estão todos listados no arquivo «dev» de requisitos para Trends.Earth, para que eles possam ser instalados navegando em um prompt de comando até a raiz da pasta de código trends.earth e digitando:

pip install -r requirements-dev.txt

Nota

Se você estiver usando Anaconda, primeiro deverá ativar um ambiente virtual Python 3.7 antes de executar o comando acima (e qualquer um dos outros comandos de chamada listados na página). Uma maneira de fazer isso é iniciando um «Anaconda prompt», seguindo as instruções nesta página do Anaconda.

PyQt

PyQt5 é o kit de ferramentas gráficas usado pelo QGIS3. Para compilar a interface do usuário do Trends.Earth for QGIS3, você precisa instalar o PyQt5. Este pacote pode ser instalado a partir do pip usando:

pip install PyQt5

Nota

PyQt4 é o kit de ferramentas gráficas usado pelo QGIS2. A melhor fonte para este pacote para Windows é o conjunto de pacotes mantidos por Christoph Gohlke na UC Irvine. Para baixar o PyQt4, selecione o pacote apropriado nesta página. Escolha o arquivo apropriado para a versão do Python que você está usando. Por exemplo, se você estiver usando o Python 2.7, escolha a versão com «cp27» no nome do arquivo. Se você estiver usando o Python 3.7, escolha a versão com «cp37» no nome do arquivo. Escolha «amd64» para python de 64 bits e «win32» para python de 32 bits.

Após fazer o download no link acima, use pip para instalá-lo. Por exemplo, para a roda de 64 bits para Python 3.7, você executaria:

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

Alterando a versão do plugin

A convenção para Trends.Earth é que os números de versão que terminam em um número ímpar (por exemplo, 0,65) são versões de desenvolvimento, enquanto as versões que terminam em um número par (por exemplo (0,66) são versões de lançamento. As versões de desenvolvimento do plug-in nunca são liberadas via o repositório QGIS, para que eles nunca sejam vistos pelos usuários normais do plug-in. Versões de desenvolvimento com números ímpares são usadas pela equipe de desenvolvimento do Trends.Earth ao testar novos recursos antes de seu lançamento público.

Se você deseja fazer alterações no código e baixou uma versão pública do plugin (que termina em um número par), a primeira etapa é atualizar a versão do plugin para o próximo número ímpar seqüencial. Portanto, por exemplo, se você baixou a versão 0.66 do plugin, seria necessário atualizar a versão para 0.67 antes de começar a fazer as alterações. Existem vários locais no código em que a versão é mencionada (assim como em todos os scripts GEE), portanto, há uma tarefa de chamada para ajudar na alteração da versão. Para alterar a versão para 0,67, você deve executar:

invoke set-version -v 0.67

A execução do comando acima atualizará o número da versão em todos os locais mencionados no código. Para evitar confusão, nunca mude a versão para uma que já foi lançada - sempre AUMENTE o valor da tag da versão para o próximo número ímpar.

Testando alterações no plugin

Depois de fazer alterações no código do plugin, você precisará testá-los para garantir que o plugin se comporte conforme o esperado e para garantir que não haja bugs ou erros. O plugin deve passar por testes extensivos antes de ser lançado no repositório QGIS (onde pode ser acessado por outros usuários) para garantir que quaisquer alterações no código não quebrem o plugin.

Para testar as alterações feitas no plugin no QGIS, será necessário instalá-lo localmente. Existem tarefas de chamada que auxiliam nesse processo. A primeira etapa antes da instalação do plug-in é garantir que você o tenha configurado com todas as dependências necessárias para executar no QGIS. Para fazer isso, execute:

invoke plugin-setup

A tarefa acima só precisa ser executada imediatamente após o download do código trends.earth ou se forem feitas alterações nas dependências do plugin. Por padrão, o plugin-setup reutiliza todos os arquivos em cache na sua máquina. Para começar do zero, adicione o sinalizador -c (clean) ao comando acima.

Após executar o plugin-setup, você está pronto para instalar o plugin na pasta de plug-ins do QGIS em sua máquina. Para fazer isso, execute:

invoke plugin-install

Depois de correr o comando em cima, precisará de ou 1) reiniciar o QGIS, ou 2) usar o Plugin Reloader para recarregar o plug-in Trends.Earth, de forma a ver os efeitos das alterações que fez.

Por padrão, plugin-install substituirá os arquivos de plugin existentes em sua máquina, mas deixará em vigor quaisquer dados (limites administrativos etc.) que o plugin possa ter baixado. Para começar do zero, adicione o sinalizador -c (clean) ao comando acima. Pode ser necessário fechar o QGIS para executar com êxito uma instalação limpa do plugin usando o sinalizador -c.

Nota

Por padrão, a instalação assume que você deseja instalar o plugin a ser usado no QGIS3. Para instalar o plug-in para uso no QGIS3, adicione o sinalizador -v 2 ao comando plugin-install. Lembre-se de que o plugin pode ou não ser totalmente funcional no QGIS3 - o plugin foi originalmente projetado para o QGIS2 e ainda está sendo testado no QGIS3.

A atualizar a lista de limites em cache

Quando o conjunto de dados geoBoundaries for atualizado, atualize a lista em cache incluída no plugin executando:

invoke download-boundaries-cache

A tarefa efetua a autenticação na API do Trends.Earth. Configure as credenciais adicionando um ficheiro invoke.yaml na raiz do repositório com entradas como:

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

Também pode fornecer as credenciais através das variáveis de ambiente TRENDS_EARTH_API_USER e TRENDS_EARTH_API_PASSWORD antes de invocar a tarefa.

Construindo um arquivo ZIP contendo o plugin

Existem várias tarefas de chamada para ajudar na criação de um arquivo ZIP para implantar o plugin no repositório QGIS ou para compartilhar a versão de desenvolvimento do plugin com outras pessoas. Para empacotar o plugin e todas as suas dependências em um arquivo ZIP que pode ser instalado seguindo o procedimento descrito no Leiame do Trends.Earth, execute:

invoke zipfile-build

Este comando criará uma pasta chamada build na raiz da pasta de código trends.earth, e nessa pasta criará um arquivo chamado LDMP.zip. Este arquivo pode ser compartilhado com outras pessoas, que podem usá-lo para instalar manualmente o Trends.Earth. Isso pode ser útil se houver a necessidade de compartilhar os recursos mais recentes com alguém antes que eles estejam disponíveis na versão divulgada publicamente do plugin.

Implementando o Arquivo ZIP da versão em desenvolvimento

A página do Trends.Earth no GitHub disponibiliza uma ligação para um ficheiro ZIP que permite aos utilizadores que não sejam programadores aceder à versão de desenvolvimento do Trends.Earth. Para criar um ficheiro ZIP e disponibilizá-lo nessa página (o ficheiro ZIP é armazenado no S3), execute:

invoke zipfile-deploy

Este comando irá empacotar o plugin e copiá-lo para https://s3.amazonaws.com/trends.earth/sharing/LDMP.zip.

Nota

O comando acima falhará se você não tiver chaves que permitam acesso de gravação ao bucket trends.earth no S3.

Modificando o código de processamento do Earth Engine

Os scripts de processamento do Google Earth Engine (GEE) usados pelo Trends.Earth são todos armazenados na pasta «gee», na pasta principal trends.earth. Para que esses scripts sejam acessíveis aos usuários do plugin trends.earth QGIS, eles precisam ser implantados no serviço api.trends.earth que a Conservação Internacional mantém para permitir que os usuários do plugin usem o Earth Engine sem a necessidade de saber como programar ou ter contas de usuário individuais no GEE. A seguir, descrevemos como testar e implantar scripts GEE para serem usados com o Trends.Earth.

Configurando dependências

docker

O pacote trends.earth-CLI requer docker para funcionar. Siga estas instruções para instalar a janela de encaixe no Windows e` estas instruções para instalar a janela de encaixe no Mac OS <https://docs.docker.com/docker-for-mac/install/>`_. Se você estiver executando o Linux, siga as instruções nesta página que são apropriados para a distribuição Linux que você está usando.

Testando um script do Google Earth Engine localmente

Depois de instalar o pacote trends.earth-CLI, você precisará configurar um arquivo .tecli.yml com um token de acesso a uma conta de serviço GEE para testar scripts no GEE. Para configurar a conta de serviço GEE para o tecli, primeiro obtenha a chave da sua conta de serviço no formato JSON (no console do Google Cloud) e, em seguida, codifique-a em base64. Forneça a chave codificada base64 ao tecli com o seguinte comando:

invoke tecli-config set EE_SERVICE_ACCOUNT_JSON key

onde «chave» é a chave da conta de serviço no formato JSON codificado em base64.

Ao converter um script que especifica o código a ser executado no GEE de JavaScript para Python, ou ao fazer modificações nesse código, pode ser útil testar o script localmente, sem implementá-lo no servidor api.trends.earth. Para fazer isso, use a tarefa de chamada run. Por exemplo, para testar o script «land_cover», vá para o diretório raiz do código Trends.Earth e, em um prompt de comando, execute:

invoke tecli-run land_cover

Isso usará o pacote trends.earth-CLI para criar e executar um contêiner de docker que tentará executar o script «land_cover». Se houver algum erro de sintaxe no script, eles aparecerão quando o contêiner for executado. Antes de enviar um novo script para api.trends.earth, sempre verifique se invoke tecli-run é capaz de executar o script sem erros.

Ao usar invoke tecli-run, você pode receber um erro dizendo:

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 erro pode ser causado se o relógio no contêiner do docker ficar fora de sincronia com o relógio do sistema. Reiniciar docker deve corrigir esse erro.

A editar modelos de camada vetorial

O Trends.Earth permite aos utilizadores digitalizar novos elementos vetoriais para delinear áreas de especial interesse.

Para já, apenas as camadas de «falso positivo/negativo» são suportadas, mas poderão ser adicionadas mais, se necessário. Qualquer camada vetorial é criada a partir dos ficheiros de modelo GeoPackage, que podem ser encontrados na pasta data/error_recode do diretório de instalação do plugin. Para cada tipo de vetor, existem 6 ficheiros de modelo, um para cada língua oficial da ONU. O código de língua ISO é adicionado como um sufixo ao nome do ficheiro. Isto é necessário para fornecer etiquetas localizadas nos formulários de atributos. Quando a criação da camada vetorial é solicitada, o QGIS procurará o ficheiro de modelo tendo em conta o idioma do QGIS; como opção de recurso, será utilizada a versão em inglês do ficheiro de modelo.

Para alterar o esquema da camada, é necessário modificar os ficheiros de modelo correspondentes na pasta data/error_recode do diretório de instalação do plugin. Além disso, o ficheiro de modelo contém uma estilização predefinida incorporada e uma configuração de formulário de atributos que serão aplicadas automaticamente à camada quando esta for carregada no QGIS.

Para apresentar gráficos no formulário atributo, é usado um widget QML integrado. Os dados para os gráficos estão guardados na tabela de atributos da camada vetorial. Os valores dos campos correspondentes são extraídos com a ajuda de expressões.

O código para gerar gráficos tem este aspeto:

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

Para extrair o valor do campo, é usada a função expression.evaluate("\"prod_deg\""), o único argumento que aceita é o nome do campo. Para camadas de falsos positivos/negativos, o gráfico contém três indicadores, produtividade, cobertura de solo e carbono orgânico do solo. Para cada indicador, o plug-in mantém três valores da área do polígono: estável, degradado e melhorado. Por exemplo, no caso do indicador produtividade, os campos serão:

  • prod_deg - produtividade degradada

  • prod_stab - produtividade estável

  • prod_imp - produtividade melhorada

A mesma abordagem de nomenclatura é aplicada à cobertura do solo (campos land_*) e ao carbono orgânico do solo (campos soil_*).

O cálculo da percentagem de área é efetuado com uma função de expressão personalizada, cujo código pode ser encontrado no ficheiro charts.py, no diretório raiz do plugin. A função está otimizada para trabalhar com polígonos de grandes dimensões e utiliza o seguinte fluxo de trabalho: para uma determinada geometria, define uma caixa envolvente e extrai um subconjunto do raster utilizando essa bbox. Realiza a rasterização da geometria em memória e aplica-a como uma máscara ao raster. Em seguida, conta o número de píxeis que possuem um valor específico e calcula a percentagem. Como a contagem de píxeis se baseia em funções de matrizes numpy, o processo é muito rápido, mesmo para polígonos grandes.

Na primeira tentativa de editar uma camada vetorial, será apresentado um diálogo ao utilizador, onde este deverá escolher os conjuntos de dados a usar para os indicadores. Depois o plug-in irá configurar os valores de expressão por defeito para todos os campos indicadores, para que o valor seja atualizado em cada alteração de geometria.

Gestão dos metadados do conjunto de dados

Os metadados dos conjuntos de dados são armazenados no formato QGIS QMD. Estes ficheiros QMD podem ser criados para cada matriz individualmente e também para todo o conjunto de dados. O diálogo do editor de metadados é aberto a partir do menu Editar metadados na plataforma Trends.Earth.

Quando o conjunto de dados é exportado para ZIP, a conversão para ISO XML é realizada usando transformação XSLT. As transformações correspondentes estão localizadas na sub-pasta data\xsl da pasta de instalação do plug-in.

A atualizar estrutura de relatório

Resumo da estrutura de relatório

A Estrutura de Relatórios foi concebida para ser extensível, proporcionando ao mesmo tempo interatividade ao utilizador, através de operações sem bloqueio. A Estrutura baseia-se fortemente nas classes QgsProject e QgsPrintLayout, que não são seguras, daí a utilização de qgis_process para fazer o trabalho pesado de gerar os relatórios (e gráficos). Pode encontrar mais informação sobre qgis_process aqui.

A caixa de ferramentas executa dois passos principais quando gera relatórios (e gráficos) para as camadas por defeito num trabalho:

  1. Cria um objeto ReportTaskContext que constitui um objeto ReportConfiguration (ver: ref:config_report_params) e um objeto Job que é representado no painel de Conjuntos de dados. Este objeto ReportTaskContext é serializado para um ficheiro JSON e depois passado como um dos argumentos num objeto ReportProcessHandlerTask (que herda de QgsTask).

  2. O objeto ReportProcessHandlerTask inicia uma instância separada de qgis_process e passa o caminho para o ficheiro JSON como uma entrada para o algoritmo de processamento trendsearth:reporttask. Este é um wrapper fino que desserializa o ficheiro para o objeto ReportTaskContext e o passa para um objeto ReportTaskProcessor, que é responsável por gerar os relatórios e o projeto QGIS do trabalho. Para algoritmos que requerem gráficos, o objeto ReportTaskProcessor passa o objeto do trabalho para um objeto AlgorithmChartsManager que verifica se existe uma configuração de gráficos definida para o algoritmo do trabalho. Se existir, gera os gráficos correspondentes como ficheiros PNG. (Ver Adiciomar Configurações de Gráfico para mais informações sobre configurações de gráficos)

O diagrama em baixo apresenta uma ilustração de alto nível deste processo:

* Clique na imagem para uma vista ampliada.

Nota

Alguns dos nomes de funções no diagrama em cima foram simplificados para fins ilustrativos. As classes cima mencionadas podem ser encontradas nos módulos LDMP.reports e LDMP.processing_provider.report.

A adicionar variáveis de layout do relatório

As variáveis do relatório fornecem informações de contexto relacionadas com um trabalho, camada (ou banda) ou Relatórios durante o processo de execução do relatório. Atualmente, a caixa de ferramentas suporta as variáveis listadas na secção Variáveis de Expressão de Esquema.

Cada variável é definida como uma namedtuple no módulo LDMP.reports.expressions e é subsequentemente atualizada e avaliada pelo objeto ReportTaskProcessor.

Siga as orientações em baixo sobre como adicionar novas variáveis de trabalho ou de camada atual.

Variável de trabalho

Permite que a informação sobre o trabalho atual - a ser executado - seja adicionada ao layout de um relatório. A informação sobre cada variável de trabalho é encapsulada num objeto JobAttrVarInfo que tem quatro atributos:

Nome de atributo

Descrição

Tipo de dados

Valor por defeito

job_attr

Nome de atributo de um objeto Job, como usado numa notação dot. Por exemplo, id corresponde a job.id. Pode até usar a notação dot para referir-se a atributos em classes internas de cadeias, por exemplo, results.uri.uri.

String

N/D

var_name

Nome da variável de layout do relatório. Deve ter o prefixo te_job_.

String

N/D

default_value

Valor por defeito a usar para var_name, aplicado principalmente ao desenhar layouts.

objeto

objeto

fmt_func

Um objeto de função que será usado para converter o valor do atributo do trabalho para um formato compatível com expressões QGIS. Por exemplo, str pode ser usado para converter o valor do id de um trabalho, de UUID para string. Também pode usar funções lambda aqui.

objeto de função

Nenhum

O fragmento de código em baixo mostra como adicionar uma variável 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),
        ...
    ]

Variável de Camada

Fornece informação sobre a camada raster atual a ser executada. Esta informação de variável está encapsulada num objeto LayerVarInfo que consiste em três atributos:

Nome de atributo

Descrição

Tipo de dados

Valor por defeito

var_name

Nome do variável de esquema de relatório of the report layout variable. Deve ter como prefixo te_current_layer_.

String

N/D

default_value

Valor por defeito a usar para var_name, aplicado principalmente ao desenhar layouts.

objeto

objeto

fmt_func

Um objeto de função que será utilizado para extrair e/ou converter um valor de um objeto QgsRasterLayer para um formato compatível com expressões QGIS. Pode utilizar funções lambda aqui.

Por exemplo, lambda layer: layer.name() devolve o nome da camada.

objeto de função

Nenhum

O fragmento de código em baixo mostra como adicionar uma variável te_current_layer_height que corresponde à altura do camada raster.

# 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 variáveis estão apenas disponíveis no âmbito do esquema.

Adiciomar Configurações de Gráfico

Os gráficos podem ser agrupados utilizando o objeto de configuração de gráficos que corresponde a um algoritmo específico. A definição de uma nova configuração de gráficos é um processo com três passos:

  1. Crie uma nova classe de gráficos que herda de BaseChart no módulo LDMP.reports.charts. Implemente a função export para especificar o tipo de gráfico, propriedades, etc utilizando a biblioteca Python Plotly incluída com o QGIS. Por fim, dentro da função export, chame a função save_image para escrever o código de objeto Figure Plotly como um ficheiro de imagem, utilizando qualquer um dos formatos suportados pela classe QImageWriter de Qt. Também pode especificar o caminho em relação com diretório de resultado de raiz, que tambémestá disponível como um atributo na classe base. Veja o fragmento de código em baixo:

    # 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

    Pode consultar a classe UniqueValuesPieChart para um exemplo mais completo.

  2. Crie uma classe configuração de gráfico chart configuration class que herda de BaseAlgorithmChartsConfiguration e implemente a função _add_charts. A classe de configuração de gráfico define basicamente quais os gráficos que serão utilizados para um dado algoritmo. O atributo layer_band_infos é uma lista de objetos LayerBandInfo que contém a camada e dados band_info necessários para produzir os gráficos. Pode consultar a classe LandCoverChartsConfiguration para um exemplo mais completo.

  3. Por fim, mapeie uma algoritmo (nome) à classe de configuração de gráficos correspondente na classe AlgorithmChartsManager tal como apresentado em baixo:

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

    A classe AlgorithmChartsManager, que é instanciada no objeto ReportTaskProcessor, irá criar um novo objeto de configuração de gráficos para o algoritmo de um trabalho correspondente quando os relatórios estiverem a ser gerados.

Contribuindo para a documentação

Sumário

A documentação para Trends.Earth é produzida usando o Sphinx, e está escrito em` reStructuredText <http://docutils.sourceforge.net/rst.html>`_ formato. Se você não for familiarizado com nenhuma dessas ferramentas, consulte a documentação para obter mais informações sobre como elas são usadas.

A documentação do Trends.Earth é armazenada na pasta «docs», no diretório principal trends.earth. Dentro dessa pasta, há vários arquivos e pastas importantes que você deve conhecer:

  • build: contém a documentação da build para trends.earth (no formato PDF e HTML). Observe que ele só aparecerá na sua máquina depois de executar a tarefa de chamada docs-build.

  • i18n: contém traduções da documentação para outros idiomas. Os arquivos aqui são normalmente processados automaticamente usando tarefas com o comando «invoke», portanto, você nunca deve ter motivos para modificar nada nesta pasta.

  • recursos: contém todos os recursos (principalmente imagens ou PDFs) mencionados na documentação. Atualmente, existe apenas uma pasta («EN», em inglês), pois todas as imagens na documentação são da versão em inglês do plugin - pastas adicionais apropriadas podem ser adicionadas em «resources» com códigos de duas letras identificando o idioma para incluir imagens específicas para um idioma específico.

  • source: contém os arquivos de origem reStructuredText que definem a documentação (esse é o texto em inglês real da documentação e os arquivos que você provavelmente precisará modificar).

Instalando dependências

Dependências do Python

Para trabalhar com a documentação, você deve ter os pacotes invoke, Sphinx, sphinx-intl e sphinx-rtd-theme (o tema do site Trends.Earth) instalados em sua máquina. Esses pacotes estão todos listados no arquivo de requisitos «dev» do Trends.Earth, para que possam ser instalados navegando em um prompt de comando até a raiz da pasta de código trends.earth e digitando:

pip install -r requirements-dev.txt

LaTeX

O LaTeX é usado para produzir saídas em PDF da documentação para Trends.Earth.

Para instalar LaTeX no Windows, siga o processo descrito aqui para instalar a distribuição proTeXt do LaTeX a partir do arquivo zip disponível aqui. O instalador do LaTeX é bastante grande (vários GB), portanto, pode levar algum tempo para baixar e instalar.

No MacOS, o MacTeX é uma boa opção e pode ser instalado seguindo as instruções aqui.

No Linux, a instalação do LaTeX deve ser muito mais fácil - use o gerenciador de pacotes da sua distribuição para encontrar e instalar qualquer distribuição do LaTeX incluída por padrão.

Qt Linguist

O Qt Linguist também é necessário para extrair strings do código e da GUI para tradução. O comando «lrelease» deve estar disponível e no seu caminho. Tente tentar

lrelease

dentro de uma janela do terminal. Se o arquivo não for encontrado, você precisará instalar o Qt Linguist. Esta página é uma fonte de instaladores para o Qt Linguist. Depois de instalar o Qt Linguist, adicione a pasta que contém lrelease ao seu caminho para que o script de chamada Trends.Earth possa encontrá-lo.

Atualizando e preparando a documentação

Depois de instalar os requisitos do pacote sphinx, você estará pronto para começar a modificar a documentação. Os arquivos a serem modificados estão localizados na pasta «docs\source». Depois de fazer alterações nesses arquivos, você precisará criar a documentação para visualizar os resultados. Existem duas versões da documentação do Trends.Earth: uma versão HTML (usada para o site) e uma versão PDF (para download offline). Para criar a documentação do Trends.Earth, use a tarefa «docs-build» do invoke. Por padrão, esta tarefa cria a documentação completa do Trends.Earth, em HTML e PDF, para todos os idiomas suportados. Isso pode levar algum tempo para ser executado (até algumas horas). Se você está apenas testando os resultados de algumas pequenas alterações na documentação, geralmente é melhor usar a opção -f (de «fast» = rápido). Esta opção criará apenas a documentação HTML em inglês, que deve levar apenas alguns segundos. Para criar usando a opção rápida, execute:

invoke docs-build -f

O comando acima levará alguns segundos para ser executado e, se você procurar em «docs\ build\html\en», verá a versão HTML da documentação. Carregue o arquivo «index.html» em um navegador da Web para ver como fica.

Para criar a documentação completa, para todos os idiomas, em PDF e HTML (lembre-se de que isso pode levar algumas horas para ser concluído), execute:

invoke docs-build

Após executar o comando acima, você verá (em inglês) a documentação HTML em «docs\build\html\en», e os PDFs da documentação em «docs\build\html\en\pdfs».

Se você quiser testar um idioma específico (testar traduções, por exemplo), poderá especificar um código de duas letras identificando o idioma para criar apenas os documentos para esse idioma. Por exemplo, para criar apenas a documentação em espanhol, execute:

invoke docs-build -l es

Observe que as opções podem ser combinadas; portanto, você pode usar a opção rápida para criar apenas a versão HTML da documentação em espanhol executando:

invoke docs-build -f -l es

Ao criar a documentação completa para o site, é uma boa idéia remover primeiro todas as versões antigas da documentação, pois elas podem conter arquivos que não são mais usados na documentação atualizada. Para fazer isso, use a opção -c (clean):

invoke docs-build -c

Em geral, a preparação dos documentos DEVE ser concluído sem erros se você planeja compartilhar a documentação ou publicá-la no site. No entanto, ao testar localmente, convém ignorar os erros de documentação que aparecem somente em alguns idiomas (devido a erros de sintaxe decorrentes de erros de tradução etc.) e continuar a compilar a documentação restante, independentemente de haver erros. Para fazer isso, use a opção -i (ignorar erros):

invoke docs-build -i

Sempre que você fizer alterações no texto da documentação, é uma boa ideia enviar as últimas atualizações para o Transifex, para que possam ser traduzidas. Para atualizar as seqüências de caracteres no Transifex com novas alterações, execute:

invoke translate-push

Nota

Para executar com êxito o comando acima, você precisará da chave da conta transifex Trends.Earth.

Preparando a documentação para publicar a nova versão

Antes de liberar a nova documentação, sempre baixe as últimas traduções do Transifex para que todas as traduções estejam atualizadas. Para fazer isso, execute:

invoke translate-pull

Para criar uma versão pública da documentação (no site ou em PDF), você deve compilar toda a documentação usando docs-build sem parâmetros adicionais:

invoke docs-build

Esse processo deve ser concluído com êxito, sem erros. Se ocorrer algum erro durante o processo, revise a mensagem de erro e faça as modificações necessárias para permitir que a compilação seja concluída com êxito. Depois que a compilação é concluída sem erros, os arquivos estão prontos para serem implementados no site.

Nota

Ambos os comandos acima também têm opções -f (force) que forçam a baixar ou subir as últimas traduções do ou para o Transifex (respectivamente). Use essas opções apenas se tiver MUITO certo do que está fazendo, pois elas podem substituir completamente as traduções no Transifex, resultando em perda de trabalho dos tradutores se as traduções mais recentes ainda não foram submetidas para o repositório github.

Adicionando novo texto de documentação

Quaisquer novos arquivos .rst adicionados à documentação precisam ser adicionados a vários arquivos de configuração para garantir que apareçam no menu de navegação, que sejam traduzidos corretamente, e (para tutoriais) para garantir que sejam gerados em PDF para que possam ser baixados para uso offline.

  • docs\source\index.rst: adicione novos arquivos .rst no local apropriado aqui para garantir que eles estejam vinculados no menu de navegação.

  • .tx\config: lista os novos arquivos .rst aqui (no mesmo formato dos outros arquivos já incluídos) para tornar o software de tradução ciente deles, para que possam ser traduzidos

  • docs\source\conf.py: se você deseja gerar um arquivo PDF da página do site, deve listar essa página na lista latex_documents. Normalmente, fazemos isso apenas para as páginas de tutoriais que queremos disponibilizar aos participantes do workshop em PDFs individuais. Todas as páginas do site serão incluídas na versão PDF do site como um todo, independentemente de estar na lista latex_documents.

Adicionando novas imagens ou outros recursos

Quaisquer novas imagens ou outros recursos (PDFs etc.) necessários à documentação devem ser adicionados em «docs\resources\en». Se desejar, é possível fazer upload de versões diferentes de uma imagem para que a imagem apareça com as traduções adequadas. Isso pode ser útil se você quiser mostrar a interface da GUI no idioma apropriado, por exemplo. Para fazer isso, primeiro faça upload de uma cópia da imagem para «docs\resourcesen» (com o texto em inglês). Em seguida, crie uma cópia da imagem com texto traduzido e coloque-a na pasta apropriada para esse idioma (por exemplo, uma imagem mostrando traduções em espanhol seria exibida em «docs\resources\es»). A versão em inglês da imagem será usada como padrão para todos os idiomas para os quais uma versão nativa da imagem não é fornecida, enquanto uma versão localizada será usada quando disponível.

Nota

Existe outra pasta, docs\source\static, que é utilizada para guardar recursos temporariamente durante a execução dos scripts que compilam a documentação do Trends.Earth. Poderá ter imagens listadas nessa pasta se alguma vez tiver compilado a documentação nessa máquina.** Esta pasta nunca deve ser utilizada para adicionar novos recursos** — os novos recursos devem ser sempre colocados em docs\resources\en ou, no caso de imagens traduzidas, na pasta específica do idioma correspondente em docs\resources.

Contribuindo como tradutor

As traduções para o plugin QGIS e também para este site são gerenciadas pelo transifex. Se você quiser contribuir com a tradução do plugin e da documentação (e gostaríamos muito de ter sua ajuda!), pode solicitar para se juntar a nossa equipe por meio de transifex, ou enviando um email para trends.earth@conservation.org.

Lançamento de uma nova versão do plugin

Sumário

O lançamento de uma nova versão do Trends.Earth envolve a atualização dos números de versão, a criação de etiquetas de git, a compilação do pacote do plugin e a sua publicação tanto no GitHub como no repositório de plugins do QGIS. O processo é simplificado através de tarefas do invoke que automatizam a maioria destes passos.

Fluxo de trabalho de lançamento

Siga estes passos para criar um novo lançamento público:

1. Atualizar o registo de alterações

Primeiro, atualize o registo de alterações (changelog) em LDMP\metadata.txt com detalhes sobre o que mudou nesta versão. Inclua o número da versão e a data de lançamento, seguidos de pontos que descrevam as novas funcionalidades, correções de erros e outras alterações.

2. Definir o número da versão

Execute a tarefa set-version para atualizar os números de versão em toda a base de código:

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

Onde X.Y.Z é o novo número da versão (ex: 2.1.20). A bandeira -m garante que os números de versão sejam também atualizados nos módulos dependentes (trends.earth-schemas e trends.earth-algorithms).

Este comando irá:

  • Atualizar o ficheiro LDMP/metadata.txt com a nova versão

  • Gerar o ficheiro LDMP/_version.py com informações do Git

  • Atualizar a versão na documentação (docs/source/conf.py)

  • Definir o sinalizador experimental com base em números de versão pares/ímpares (par = estável, ímpar = desenvolvimento)

  • Atualizar as referências de dependências nos ficheiros de requisitos

Nota

Para lançamentos estáveis (números de versão pares, como 2.1.18), a tarefa set-version atualizará as referências de dependência para utilizarem versões etiquetadas. Para lançamentos de desenvolvimento (números de versão ímpares, como 2.1.19), utilizará o ramo principal.

3. Atualizar os scripts do GEE (se aplicável)

Se tiver feito alterações nos scripts do Google Earth Engine (na pasta gee) ou nos repositórios trends.earth-schemas ou trends.earth-algorithms, adicione a flag -g ao executar o comando set-version``:

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

Isto irá atualizar os números das versões em todos os ficheiros de configuração dos scripts do GEE. Antes de publicar, crie etiquetas de lançamento para os repositórios dependentes, de modo a que os scripts do GEE resolvam as versões corretas:

# 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

Assim que ambas as dependências estiverem etiquetadas, publique os scripts atualizados no servidor da API do Trends.Earth:

invoke tecli-publish

Isto carrega todos os scripts do GEE para o api.trends.earth, de modo a que fiquem disponíveis para os utilizadores do plugin. Deve ser administrador para executar este comando com sucesso.

4. Confirmar todas as alterações

Certifique-se de que todos os ficheiros modificados foram submetidos no git:

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

5. Criar e enviar etiquetas de git

Após submeter as alterações de lançamento neste repositório, execute o comando invoke set-tag:

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

Isto cria a etiqueta anotada de git do plugin (ex: v2.1.20) e envia-a para o GitHub. Se tiver alterações por submeter, a tarefa irá solicitar que as submeta primeiro.

​6. Criar o lançamento no GitHub

Execute a tarefa release-github para criar um lançamento no GitHub com o ficheiro zip do plugin em anexo:

invoke release-github

Este comando irá:

  • Gerar um ficheiro zip limpo do plugin (ex: LDMP_2.1.20.zip) com todas as dependências

  • Remover todos os ficheiros .pyc para cumprir os requisitos de segurança do repositório do QGIS

  • Criar um lançamento no GitHub com o ficheiro zip do plugin anexado como um ativo descarregável

Nota

Irá necessitar de um token de acesso pessoal do GitHub com o âmbito repo configurado no seu ficheiro invoke.yaml para que este comando funcione. Caso a autenticação falhe, consulte as mensagens de erro para obter instruções sobre como criar um token.

​7. Publicar no repositório do QGIS

Por fim, carregue manualmente o plugin para o repositório de complementos do QGIS:

  1. Descarregue o ficheiro zip do plugin (ex: LDMP_2.1.20.zip) a partir do lançamento do GitHub que acabou de criar (este estará listado na secção «Assets»).

  2. Inicie sessão no repositório de complementos do QGIS

  3. Navegue até à sua página de gestão de complementos

  4. Carregue a nova versão utilizando o ficheiro zip

O repositório do QGIS irá validar o ficheiro zip e disponibilizá-lo aos utilizadores através do gestor de complementos do QGIS.

Convenções de Numeração de Versões

O Trends.Earth segue as seguintes convenções de numeração de versões:

  • O Trends.Earth segue as seguintes convenções de numeração de versões:

  • Números ímpares (ex: 2.1.19, 2.1.21): Lançamentos de desenvolvimento para testar novas funcionalidades.

As versões de desenvolvimento nunca são publicadas no repositório do QGIS e são utilizadas apenas pela equipa de desenvolvimento para a realização de testes.