Mergin Maps

Aparência

Redigir documentação ​

Obrigado pelo seu interesse em ajudar na redação Mergin Maps Documentação. A estrutura de documentação baseia-se em VitePress. Agradecemos quaisquer contribuições, tais como Pedidos de integração no GitHub. Se não souber como contribuir ou por que tarefas começar, junte-se a nós no nosso comunidade e pergunte. Teremos todo o prazer em o pôr a par de tudo!

A versão da documentação que vê em Mergin Maps Documentação é o último lançamento com etiqueta no ramo principal. O último commit no ramo principal pode ser consultado em Mergin Maps Documentação de preparação.

Introdução rápida ​

Se estiver prestes a fazer apenas uma pequena alteração na documentação, pode saltar esta secção e passar diretamente para as instruções sobre como corrigir um erro ortográfico ou fazer pequenas alterações na documentação.

Se é um (web) programador, pode ignorar tudo e limitar-se a ver Mergin Maps README.

Caso contrário, é melhor realizar o desenvolvimento local no seu computador. Os passos semelhantes aos descritos podem ser seguidos em (quase) qualquer sistema operativo, com pequenas adaptações (por exemplo, utilizando infusão ou adequado no macOS ou no Linux para instalação).

Se não fazes parte da Mergin Maps equipa principal de documentação, terá de trabalhar com um fork. Siga as instruções na secção «Quando é necessário um fork». Temos todo o gosto em incluir mais pessoas na equipa, por isso, se estiver a pensar em escrever mais documentação, informe-nos na nossa comunidade.

Preparar o repositório local ​

Como requisito, é necessário que instalar o Git.

Depois de instalado, abra a linha de comandos/terminal e clone o repositório localmente (pode utilizar HTTP ou SSH)

cd MyProjects
git clone git@github.com:MerginMaps/docs.git

Iniciar o servidor local ​

Para poder ver as suas alterações de forma interativa, tem de executar um servidor VitePress local. Além disso, tem de instalar o yarn.

Depois de instalado, pode prosseguir com a instalação de todos os pacotes dependentes e com o arranque do servidor:

cd MerginMaps/docs
yarn install 
yarn dev

Agora já podes abrir http://localhost:5173/docs/ no teu navegador e vê a versão em tempo real da documentação.

Preparar pedidos de integração ​

Para enviar as suas alterações para a documentação oficial, tem de preparar um pedido de integração.

Comece sempre por atualizar o seu repositório para a versão mais recente:

cd MerginMaps/docs
git checkout main
git pull origin main

O próximo passo é criar um novo ramo para o seu trabalho. É aconselhável utilizar um nome de ramo descritivo:

git checkout -b my_docs_fix_branchname

Agora já pode editar os ficheiros Markdown no seu editor de texto preferido. Recomendamos que verifique as alterações à medida que avança na versão dos documentos executada localmente http://localhost:5173/docs/.

Quando terminar, faça o commit das alterações e envie o seu ramo para o GitHub:

git status
git add .
git commit -m "Documentação melhorada de XXX"
git push origin my_docs_fix_branchname

Agora vai a GitHub e criar um pedido de integração (a partir da Web ou utilizando o link no terminal).

Verifica os testes automáticos nas solicitações de integração para detetar erros ortográficos, problemas com Markdown, links inválidos ou redirecionamentos e, se necessário, corrige os problemas no teu código.

Para garantir que o teu pedido de integração seja analisado e integrado, é aconselhável contactar a Mergin Maps equipa de documentação na comunidade.

Quando é necessário utilizar o garfo ​

AVISO

Pode ignorar este passo se for membro da Mergin Maps equipa de documentação e tiver permissões de escrita no repositório.

Fazer um fork MerginMaps/docs repositório com o código-fonte da documentação; siga os passos descritos em Documentação do GitHub.

Vais acabar com o fork de MerginMaps/docs no seu espaço de nomes.

Se utilizar o fork, terá de adicionar tanto o fork como o upstream ao seu espaço de nomes local:

mkdir MerginMaps; cd MerginMaps
git clone git@github.com:<my_fork_of_MerginMaps/docs>.git
git remote add upstream git@github.com:MerginMaps/docs.git

Também é necessário atualizar o seu fork remoto antes de começar a trabalhar:

cd MerginMaps/docs
git checkout main
git pull upstream main
git push origin main

Como corrigir um erro ortográfico na documentação ​

Se encontrar um erro ortográfico ou outro problema numa página que possa ser facilmente corrigido, pode deslocar-se até ao final da página para ver um rodapé semelhante a este

Mergin Maps rodapé da página de documentação

Utilize a ligação «Ajude-nos a melhorar esta página» para aceder ao código-fonte Markdown editável da página. Se não fizer parte da Mergin Maps equipa principal de documentação, também terá de trabalhar num fork para poder prosseguir.

Por que é que o Markdown tem um conteúdo diferente do da documentação pública? ​

Por vezes, pode acontecer que a ligação no rodapé esteja inativa ou que o conteúdo em Markdown não corresponda ao conteúdo da documentação doMergin Maps .

Isto deve-se ao facto de a versão lançada ser a último lançamento com etiqueta. O último commit no ramo principal pode ser consultado no servidor de teste Mergin Maps Documentação de preparação.

O sistema de documentação ​

A nossa documentação inspira-se neste sistema de documentação. Cada página deve ser redigida de acordo com um dos quatro tipos básicos de documentação: tutoriais, guias práticos, referência técnica e conceitos (explicação).

Em geral, os tutoriais encontram-se na secção «Começar ».

As restantes secções seguem esta lógica:

  • explicar os conceitos no início da secção/subsecção
  • seguindo-se uma série de guias práticos e exemplos de utilização
  • A referência técnica encontra-se no final da secção/subsecção

As referências a outros artigos, publicações de blogue ou recursos devem ser acompanhadas de links, sempre que relevante, quer como sugestões, quer como secções intituladas «Leitura adicional ».

Títulos, cabeçalhos, nomes das barras laterais ​

Utilize componentes personalizados para referenciar nomes, o que nos permite alterá-los rapidamente, se necessário. Tenha em atenção que os componentes personalizados não funcionam em elementos como nomes de componentes de URL, links de âncora, títulos, páginas ou barra lateral.

Nestas situações:

  • Nomes dos ficheiros: mergin-maps-mobile
  • Títulos/Barra lateral: Aplicação móvel « Mergin Maps »

Para títulos (#) e barra lateral escrever com maiúscula a primeira letra de todos palavras e Nunca encurte os nomes dos componentes (por exemplo, a aplicação móvel « Mergin Maps »)

  • Correto: «Abrir dados de levantamento no seu computador»
  • Errado: «Abrir dados de inquérito no seu computador»

Para cabeçalhos (##, ###, #### ) escreva com maiúscula apenas a primeira letra de primeiro palavra e nunca abreviar os nomes dos componentes (por exemplo, Mergin Maps aplicação móvel)

  • Correto: «Colocar o seu projeto na nuvem»
  • Errado: «Colocar o seu projeto na nuvem»

Os títulos e cabeçalhos devem conter palavras-chave específicas para que sejam apresentados resultados de pesquisa relevantes:

  • Correto: «Mais informações sobre projeções e transformações»
  • Errado: «Leituras complementares»

Projetos de exemplo, utilizadores e espaços de trabalho ​

Todos os projetos mencionados na documentação utilizam Mergin Maps espaço de trabalho documentação. Certifique-se de que estes projetos são público.

No caso dos utilizadores mencionados na documentação (por exemplo, em capturas de ecrã ou em textos), é aconselhável utilizar termos genéricos Mergin Maps utilizadores jack, Jill, Sarah, etc. e espaços de trabalho genéricos.

Para citar imagens online, podemos utilizar, por exemplo:

Mergin Maps imagem de exemplo

Estrutura da pasta de documentação ​

Cada secção da documentação (por exemplo, «Introdução», «Instalação e registo», «Gerir conta e projeto», ...) tem a sua própria pasta.

Da mesma forma, todas as páginas têm a sua subpasta dentro das secções. Todos os ficheiros Markdown são guardados como index.md ficheiros nas subpastas das páginas.

AVISO

Cada pasta na pasta «docs» só pode conter um ficheiro Markdown. Este ficheiro tem de ter o nome index.md. Por favor, evite criar ficheiros Markdown com outros nomes (por exemplo, page.md).

Adicionar uma nova página ​

Para adicionar uma nova página, crie uma pasta na secção correspondente. Esta pasta deve conter ficheiros relevantes, tais como index.md e imagens.

Esta página deverá ficar assim:

  • adicionado à barra lateral src/.vitepress/sidebar/en.js (note-se que a ordem dos artigos no menu é sempre «conceitos - como fazer - referência»)
  • adicionado à página de destino src/index.md

Se a página contiver vários cabeçalhos, inclua o Índice no início, utilizando [[toc]].

Imagens ​

As imagens devem estar localizadas na mesma pasta que o ficheiro Markdown index.md ficheiro que faz referência a eles.

Todas as imagens utilizadas na documentação devem ter um ficheiro GIMP associado .xcf ficheiro que contém a imagem original em resolução total.

As imagens devem ser exportadas para webp (de preferência) ou jpg formato. O seu tamanho não deve exceder 150 kb. Apenas as imagens em que os detalhes ampliados sejam importantes podem ter um tamanho superior.

Capturas de ecrã de QGIS devem:

  • deve ser capturada com a janela com as dimensões 1024x768
  • ter botões/barras de ferramentas consistentes em QGIS
  • Windows/macOS, não Linux
  • ter caixas de diálogo tão pequenas quanto possível, sem barras de deslocamento nem outros elementos visuais desagradáveis

Capturas de ecrã da aplicação móvel devem:

  • ser apresentado sem espaços em branco desnecessários (por exemplo, num modo de ecrã dividido) para garantir a melhor legibilidade
  • ser reduzida numa escala de 1,5 (dependendo da resolução do ecrã do dispositivo móvel) antes da exportação, para diminuir o tamanho da imagem

Destaque ​

As partes relevantes das imagens devem ser destacadas da seguinte forma:

  • adicionar uma nova camada chamada Preto com 66% de opacidade, preencha-o com a cor preta
  • adicionar uma nova camada chamada Vermelho com 100 % de opacidade
  • selecione com precisão o que pretende destacar e Seleção de culturas por:
    • Computador de secretária: 3px
    • Dispositivos móveis: 24 px
  • eliminar a seleção de Preto camada
  • contorne a seleção com a cor vermelha no Vermelho camada, com largura:
    • Computador de secretária: 3px
    • Dispositivos móveis: 12px

Títulos e textos alternativos ​

Todas as imagens utilizadas na documentação devem ter um título e um texto alternativo (exceto imagens decorativas, como ícones, que não fazem parte da documentação):

![texto alternativo da imagem](./myimage.png "título da imagem")

O atributo «title» da imagem fica visível ao passar o rato por cima. Mostrará o título sobre a imagem.

O texto alternativo da imagem serve para descrever as imagens aos utilizadores que não as conseguem ver. É utilizado quando se utiliza um leitor de ecrã ou caso a imagem não seja carregada.

Para textos:

  • Em geral, utiliza o mesmo texto para os atributos «alt» e «title»
  • Seja específico e sucinto; o ideal é utilizar cerca de 5 a 7 palavras e menos de 125 caracteres
  • usa as palavras-chave com moderação, descreve-o com palavras simples
  • incluir texto que faça parte da imagem
  • Nunca comece com «Imagem de…» ou «Fotografia de…»

Utilizar o Markdown ​

Se não estiver familiarizado com o Markdown, o melhor é seguir algum tutorial ou utilizar uma ficha de referência.

Para além do Markdown normal, pode utilizar etiquetas HTML, bem como alguns componentes adicionais descritos nesta secção.

Índice e Esboço ​

Utilização [[toc]] para gerar o índice.

Utilização esboço na parte inicial da página, para definir qual o cabeçalho que deve aparecer no Índice:

---
esboço: detalhado
---

ou

---
esboço: [número, número]
---

Faça referência a outros ficheiros Markdown utilizando um caminho relativo em relação ao ficheiro atual.

Consulte o pasta, e não o index.md o próprio ficheiro.

Para referenciar uma página, a referência deve terminar com uma barra /, por exemplo:

[ver aqui](../misc/write-docs/)

Para fazer referência a um título/âncora, utilize #, por exemplo:

[ver aqui](../misc/write-docs/#links)

Referenciar imagens ​

As imagens são referenciadas através de caminhos relativos, por exemplo:

  • ![texto alternativo da imagem](./myimage.jpg "título da imagem") se a imagem estiver na mesma pasta que o ficheiro Markdown
  • ![texto alternativo da imagem](../../section/myimage.jpg "título da imagem") se a imagem estiver numa pasta diferente da do ficheiro Markdown

Para imagens/recursos globais colocados em /src/public/ utilizar um componente personalizado <PublicImage />, por exemplo: <PublicImage src="lutra-logo.png" title="Lutra Consulting Ltd. logo" />:

indefinido

Caixa de dicas/avisos/informações/erros/notas ​

Utilize a caixa de texto para dicas, avisos, erros ou detalhes, quando for o caso. Recomenda-se utilizar um título personalizado.

DICA

exemplo de dica

::: dica 
exemplo de dica
:::

AVISO

exemplo de aviso

::: aviso 
exemplo de aviso
:::

PERIGO

exemplo de perigo

::: perigo 
Exemplo de perigo 
:::
Detalhes

exemplo detalhado

::: detalhes 
exemplo de detalhes 
:::

Títulos personalizados para caixas de informação ​

As caixas informativas podem ter títulos personalizados:

Título personalizado

Exemplo de título personalizado

::: aviso Título personalizado
Exemplo de título personalizado
:::

Emoji ​

Pode utilizar qualquer um dos formatos suportados emojis suportados pelo projeto markdown-it, por exemplo:

🎉 😀 🤣 😱 ❤️ 🙏 ✅ 🚫

:tada: :grinning: :rofl: :scream: :heart: :pray: :white_check_mark: :no_entry_sign:

Etiquetas/distintivos ​

O Markdown permite a utilização de emblemas, tais como:

distintivo de gorjeta
markdown
<Badge text="tip badge" type="tip"/>
distintivo de aviso
markdown
<Badge text="warning badge" type="warning"/>
ícone de erro
markdown
<Badge text="error badge" type="danger"/>

Para indicar que uma determinada funcionalidade está disponível a partir de uma versão específica, utilize <SinceBadge />

markdown
<SinceBadge type="App" version="2022.1.1" />
Desde a aplicação móvel 2022.1.1
markdown
<SinceBadge type="Plugin" version="2023.2" />
Desde o plugin « QGIS » 2023.2
markdown
<SinceBadge type="Server" version="2024.3" />
A partir do Server 2024.3

Para se referir a Mergin Maps EE ou Mergin Maps CE edição, utilização <ServerType />

markdown
<ServerType type="CE" />
Apenas na Edição Comunitária
markdown
<ServerType type="EE" />
Apenas na Enterprise Edition

Componentes personalizados para Markdown ​

ver src/.vitepress/components/ para ver a lista de todos os componentes

Se estiver a adicionar um novo componente:

  • adicione o seu componente a src/.vitepress/components/MyComponent.vue
  • utilizar no Markdown como <MyComponent></MyComponent> ou <MyComponent />
  • incluí-lo nesta página, na secção pertinente (por exemplo, componentes «Mergin Maps »)

Consulte as páginas de ajuda em QGIS e QGIS ​

Para fazer referência a um sit QGIS , utilize <QGIS /> componente, por exemplo,

<QGIS link="en/site/forusers/download.html" text="QGIS Download page" />

transforma-se em

QGIS DocumentaçãoQGIS Descarregar a página

Para consultar a documentação de QGIS , utilize <QGISHelp /> componente, por exemplo,

<QGISHelp ver="latest" link="user_manual/index.html" text="See QGIS Help page" />

transforma-se em

QGIS DocumentaçãoConsulte a página de ajuda de « QGIS »

Consultar o conteúdo do GitHub ​

Utilização <GitHubRepo /> componente, por exemplo, <GitHubRepo id="MerginMaps/docs/" desc="documentation" /> transforma-se em documentação.

Mergin Maps componentes ​

Geral ​

Utilização <MainDomainName /> componente, transforma-se em merginmaps.com

Utilização <MainDomainNameLink /> componente, transforma-se em merginmaps.com

Utilização <MainPlatformName /> componente, transforma-se em Mergin Maps

Utilização <MainPlatformNameLink /> componente, transforma-se em Mergin Maps

Utilização <LutraConsultingName /> componente, transforma-se em Lutra Consulting Lda.

Utilização <LutraConsultingWeb /> componente, transforma-se em Lutra Consulting Lda.

Utilização <DockerHubLink /> componente, transforma-se em Mergin Maps repositório do Docker

Aplicação móvel ​

Utilização <MobileAppName /> componente, transforma-se em Mergin Maps aplicação móvel

Utilização <MobileAppNameShort /> componente, transforma-se em aplicação móvel

QGIS plugin ​

Utilização <QGISPluginName /> componente, transforma-se em Mergin Maps QGIS plug-in

Utilização <QGISPluginNameShort /> componente, transforma-se em QGIS plugin

Servidor ​

Utilização <AppDomainNameLink /> componente, transforma-se em app.merginmaps.com

Utilização <DashboardLink /> componente, transforma-se em Mergin Maps painel de controlo

Utilização <DashboardShortLink /> componente, transforma-se em painel de controlo

Utilização <ServerCloudName /> componente, transforma-se em Mergin Maps Nuvem

Utilização <ServerCloudNameLink /> componente, transforma-se em Mergin Maps Nuvem

Utilização <CommunityPlatformName /> componente, transforma-se em Mergin Maps CE

Utilização <CommunityPlatformNameLink /> componente, transforma-se em Mergin Maps CE

Utilização <EnterprisePlatformName /> componente, transforma-se em Mergin Maps EE

Utilização <EnterprisePlatformNameLink /> componente, transforma-se em Mergin Maps EE

Referência: projeto « Mergin Maps » ​

Utilização <MerginMapsProject /> componente, por exemplo, <MerginMapsProject id="documentation/test_forms" /> transforma-se em Mergin Maps Documentação do projeto/formulários de testedocumentação/formulários_de_teste .

Para uma referência breve (por exemplo, em tabelas), utilize <MerginMapsProjectShort /> componente, por exemplo, <MerginMapsProject id="documentation/test_forms" /> transforma-se em Mergin Maps Documentação do projeto/formulários de teste .

Mostrar os ícones do Google e da Apple para descarregar a aplicação móvel « Mergin Maps » ​

Utilização <AppDownload /> componente a apresentar

Descarregar na App StoreDescarrega-o no Google PlayDisponível no Windows

Incorporar conteúdo do YouTube ​

Utilização <YouTube /> componente, por exemplo, <YouTube id="DQXrINUqiFI" title="Title of video" /> transforma-se em

Verificação ortográfica ​

Pode acontecer que seja necessário utilizar uma palavra ou uma sequência de caracteres que não seja aprovada pelo corretor ortográfico.

Para omitir a verificação ortográfica de uma única palavra que se prevê que seja utilizada apenas algumas vezes, utilize o seguinte componente:

Sem correção ortográfica, por exemplo: <NoSpellcheck id="myword" />

As palavras que vão ser utilizadas várias vezes podem ser adicionadas à /scripts/wordlist.txt para ser excluída definitivamente da verificação ortográfica.

Pesquisar na documentação ​

A pesquisa de texto completo é utilizada na documentação graças ao leo-buneev/vuepress-plugin-fulltext-search plug-in.

Traduções ​

As traduções ainda não são suportadas/implementadas.

Redirecionamentos ​

À medida que a documentação evolui, as páginas são movidas, renomeadas ou eliminadas. Como os sites de terceiros podem conter ligações para essas páginas, é importante manter informações sobre como redirecionar as ligações que já não existem para algo útil.

Esta informação é registada no REDIRECÇÕES ficheiro.

Atualização do ficheiro REDIRECTS ​

O ficheiro REDIRECTS é uma lista, separada por tabulações, de pares de URLs antigas e novas. Descreve como os pedidos de conteúdo antigo devem ser redirecionados.

Com uma ideia clara de como a estrutura do conteúdo irá mudar numa determinada versão (ver acima), atualize os REDIRECTS da seguinte forma:

  • Páginas renomeadas (.md) ou ficheiros de dados (por exemplo, .json, .zip):
    • Adicione uma nova linha ao ficheiro REDIRECTS para refletir esta alteração
    • Verifique se as linhas existentes no ficheiro REDIRECTS apontam para a página/ficheiro de dados que está a ser renomeado
      • Se for esse o caso, atualize essas referências para que apontem para o novo caminho da página ou do ficheiro de dados renomeado
  • Páginas eliminadas (.md):
    • Adicione uma nova linha ao ficheiro REDIRECTS para redirecionar os pedidos para um destino adequado
    • Verifique se as linhas existentes no ficheiro REDIRECTS apontam para a página eliminada
      • Se for esse o caso, atualize esses alvos para que apontem para algum local adequado
  • Imagens renomeadas (por exemplo, .png, .jpg) e ficheiros de dados eliminados (por exemplo, .json, .zip):
    • Por enquanto, ignoramos estes aspetos
  • Verificações gerais
    • Certifique-se de que os URLs de origem e de destino estão separados por uma única tabulação, e não por espaços
    • Certifique-se de que todos os URLs de destino terminam com um / por exemplo:
      • https://merginmaps.com/docs/howto/input_ui/ ✅
      • https://merginmaps.com/docs/howto/input_ui 🚫

Ver o que mudou ​

Quando todos os autores tiverem submetido as suas alterações ao ramo principal e estiverem prontos para o lançamento do site, podemos facilmente obter uma visão clara do que foi alterado.

Podemos fazer isto comparando o estado atual do ramo principal com a última versão publicada do site da documentação. Para tal, proceda da seguinte forma:

  1. Comparar alterações
    • Utilize a etiqueta mais recente à esquerda
    • Utilize o «main» à direita

    GitHub: comparação de alterações

  2. Desça um pouco a página e clique onde diz 224 ficheiros alterados ou algo semelhante

    Deve agora ver, abaixo, um bom resumo dos ficheiros que foram adicionados, renomeados ou eliminados

    Resumo das alterações no GitHub

Agora já pode ver quais os conteúdos que foram alterados.