2. Guía de Redacción

En general, al crear la documentación reST para el proyecto QGIS, siga las documentación de líneas guía de estilo Python. Para mayor comodidad, proporcionamos un conjunto de reglas generales en las que confiamos para escribir la documentación de QGIS a continuación.

2.1. Escribir Documentación

2.1.1. encabezados

a cada webpage de la documentación le corresponde un archivo «.rst»

Las secciones utilizadas para estructurar el texto se identifican a través de su título que está subrayado (y subrayado para el primer nivel). Los títulos del mismo nivel deben usar el mismo carácter para subrayar el adorno. En la documentación de QGIS, debe utilizar los siguientes estilos para capítulo, sección, subsección y minisec.

********
Chapter
********

Section
=======

Subsection
----------

Minisec
.......

Subminisec
^^^^^^^^^^

2.1.2. Listas

Las listas son útiles para estructurar el texto. Aquí hay algunas reglas simples comunes a todas las listas:

  • Empiece todas las listas de elementos con una letra mayúscula

  • No use puntación tras los elementos de lista que solo continene una sentencia sencilla simple

  • Use punto ( . ) como puntuación para elementos de la lista que constan de varias oraciones o una sola oración compuesta

2.1.3. Etiquetas en línea

Puede usar etiquetas para enfatizar elementos.

  • Menu IGU: para marcar una secuencia completa de selecciones de menú, incluida la selección de submenús y la elección de una operación específica, o cualquier subsecuencia de dicha secuencia.

    :menuselection:`menu --> submenu`

  • Dialogos y títulos de pestañas: Etiquetas presentadas como parte de una interfaz de usuario interactiva que incluye títulos de ventanas, títulos de pestañas, etiquetas de botones y opciones.

    :guilabel:`title`

  • Nombres de archivo y directorios

    :file:`README.rst`

  • Iconos con texto emergente

    |icon| :sup:`popup_text`

    (ver `image`_debajo).

  • Atajos de teclado

    :kbd:`Ctrl+B`

    mostrará Ctrl+B

    Al describir atajos de teclado, se deberán usar el siguiente convenio:

    • Las teckas de letras son mostradas usando mayúsculas: S

    • Teclas especiales son mostradas con una primera letra mayúscula: Esc

    • Las combinaciones de tecla son mostradas con un signo + entre teclas, sin espacios: Shift+R

  • Texto del usuario

    ``label``

2.1.4. Etiquetas/referencias

Los vínculos dentro del texto se pueden utilizar para crear hipervínculos a secciones o páginas.

El siguiente ejemplo crea el vínculo de una sección (por ejemplo, Etiqueta/título de referencia)

.. _my_anchor:

Label/reference
---------------

Para llamar a la referencia en la misma página, use

see my_anchor_ for more information.

Que devolverá:

ver my_anchor para mas información.

Observe que saltará a la línea/cosa que sigue al “vínculo”. No es necesario que utilice apóstrofes, pero debe tener líneas vacías después del vínculo.

Otro modo para saltar al mismo lugar desde cualquier sitio en la documentación es usar la función :ref:.

see :ref:`my_anchor` for more information.

que creará un enlace con la leyenda en su lugar (en este caso, el título de esta sección):

ver Etiquetas/referencias para mas información.

Entonces, referencia 1 (my_anchor) y referencia 2 (Etiquetas/referencias). Debido a que la referencia a menudo muestra un título completo, no es realmente necesario utilizar la palabra sección. Tenga en cuenta que también puede utilizar un título personalizado para describir la referencia:

see :ref:`Label and reference <my_anchor>` for more information.

que devuelve:

ver Label and reference para mas información.

2.1.5. Figuras e Imágenes

Imágenes

Para insertar una imagen, use

.. figure:: /static/common/logo.png
   :width: 10 em

Que devolverá

../../_images/logo.png

Reemplazo

Puede poner una imagen dentro del texto o agregar un alias para usar en todas partes. Para usar una imagen dentro de un párrafo, primero cree un alias en el archivo fuente/sustituciones.txt:

.. |nice_logo| image:: /static/common/logo.png
               :width: 1 em

luego llámalo en tu párrafo:

My paragraph begins here with a nice logo |nice_logo|.

Así es como se mostrará el ejemplo:

Mi párrafo empieza aquí con un agradeble logo nice_logo.

Para permitir la representación de vista previa en GitHub que sea lo más cercana posible a la representación HTML, también deberá agregar la llamada de reemplazo de imagen al final del archivo que cambió. Esto se puede hacer copiándolo y pegándolo desde substitutions.txt o ejecutando el script scripts/find_set_subst.py .

Nota

Actualmente, para garantizar la coherencia y ayudar en el uso de los iconos de QGIS, se crea una lista de alias y está disponible en el capítulo Sustituciones.

Figura

.. _figure_logo:

.. figure:: /static/common/logo.png
   :width: 20 em
   :align: center

   A caption: A logo I like

El resultado se ve así:

../../_images/logo.png

Figura 2.18 Un título: un logo que me gusta

Para evitar conflictos con otras referencias, siempre comience los anclajes de figura con _figure_ y use términos que se relacionen fácilmente con el título de la figura. Si bien solo la alineación centrada es obligatoria para la imagen, no dude en utilizar cualquier otra opción para las figuras (como width, height, scale…) si es necesario.

Los scripts insertarán un número generado automáticamente antes del título de la figura en las versiones HTML y PDF generadas de la documentación.

Para usar un título (ver Mi título) simplemente inserte el texto sangrado después de una línea en blanco en el bloque de figuras.

Se puede hacer referencia a una figura usando la etiqueta de referencia como esta:

see :numref:`figure_logo`

se representa como esto:

vea Figura 2.18

Este es el modo prefereido de referenciar figuras.

Nota

Para que :numref: trabaje, la figura debe tener un título.

Evite usar :ref: en lugar de :numref: para referencia, ya que esto devuelve el título completo de la imagen.

see :ref:`figure_logo`

se representa como esto:

ver:ref:figure_logo

Tablas

Una tabla simple puede codificarse como esto

=======  =======  =======
x        y        z
=======  =======  =======
1        2        3
4                 5
=======  =======  =======

Se representará como esto:

x

y

z

1

2

3

4

5

Use un \ (barra invertida) seguida de un espacio vacío para dejar un espacio vacío.

También puede crear tablas más complicadas y hacer referencia a ellas:

.. _my_drawn_table:

+---------------+--------------------+
| Windows       | macOS              |
+---------------+--------------------+
| |win|         | |osx|              |
+---------------+--------------------+
| and of course not to forget |nix|  |
+------------------------------------+

My drawn table, mind you this is unfortunately not regarded as a caption

You can reference it like this: my_drawn_table_.

El resultado:

Windows

macOS

win

osx

y por supuesto no olviden nix

Mi tabla dibujada, ten en cuenta que, lamentablemente, esto no se considera un título

Puedes hacer referencia a él así my_drawn_table.

Para tablas aún más complejas, es más fácil de usar list-table:

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - What
     - Purpose
     - Key word
     - Description
   * - **Test**
     - ``Useful test``
     - complexity
     - Geometry.  One of:

       * Point
       * Line

El resultado:

Que

Propósito

Palabra clave

Descripción

Test

Useful test

complejidad

Geometría. Una de:

  • Punto

  • Línea

2.1.6. Índice

Un índice es una forma práctica de ayudar al lector a encontrar información en un documento. La documentación de QGIS proporciona algunos índices esenciales. Hay algunas reglas que nos ayudan a proporcionar un conjunto de índices que son realmente útiles (coherentes, consistentes y realmente conectados entre sí):

  • Un índice debe ser legible, comprensible y traducible; se puede hacer un índice a partir de muchas palabras, pero debe evitar los caracteres _, - … innecesarios para vincularlos, es decir, Loading layers en lugar de loading_layers o loadingLayers.

  • Escriba en mayúscula solo la primera letra del índice a menos que la palabra tenga una ortografía particular. Por ejemplo, Loading layers, Atlas generation, WMS, pgsql2shp.

  • Esté atento a la lista Índice existente para reutilizar la expresión más conveniente con la ortografía correcta y evitar duplicados innecesarios.

Existen varias etiquetas de índice en RST. Puede utilizar la etiqueta en línea :index: dentro del texto normal:

QGIS can load several :index:`Vector formats` supported by GDAL/OGR ...

O puede usar el marcado a nivel de bloque .. index:: que enlaza con el comienzo del siguiente párrafo. Debido a las reglas mencionadas anteriormente, se recomienda utilizar la etiqueta de nivel de bloque:

.. index:: WMS, WFS, Loading layers

También se recomienda utilizar parámetros de índice como single, pair and see, para construir una tabla de índice más estructurada e interconectada. Ver Generación de índices para ams información sobre creación de índices.

2.1.7. Comentarios Especiales

A veces, es posible que desee enfatizar algunos puntos de la descripción, ya sea para advertir, recordar o dar algunas pistas al usuario. En la documentación de QGIS, utilizamos directivas especiales reST como .. warning::, .. seealso::`, ``.. note:: and .. tip::. Estas directivas generan marcos que resaltan sus comentarios. Consulte Marcado de nivel de párrafo para obtener más información. Se requiere un título claro y apropiado tanto para advertencias como para sugerencias.

.. tip:: **Always use a meaningful title for tips**

   Begin tips with a title that summarizes what it is about. This helps
   users to quickly overview the message you want to give them, and
   decide on its relevance.

2.1.8. Fragmentos de código

También puede dar ejemplos e insertar fragmentos de código. En este caso, escriba el comentario debajo de una línea con la directiva ``::”” insertada. Para una mejor representación, especialmente para aplicar resaltado de color al código de acuerdo con su idioma, use la directiva de bloque de código, p. ej. ``.. code-block::xml””. Más detalles en Mostrando código.

Nota

Si bien los textos de los marcos de notas, sugerencias y advertencias son traducibles, tenga en cuenta que los marcos de bloques de código no permiten la traducción. Por lo tanto, evite los comentarios que no estén relacionados con el código y mantenga los comentarios lo más breves posible.

2.1.9. Notas al pie

Tenga en cuenta que ningún software de traducción reconoce las notas a pie de página y tampoco se convierte correctamente a formato pdf. Entonces, si es posible, no use notas al pie de página en ninguna documentación.

Esto es para crear una nota al pie (que se muestra como ejemplo 1)

blabla [1]_

Que apuntará a:

1

Actualizaciones de complementos núcleo

2.2. Manejando Capturas de Pantalla

2.2.1. Adicionar nuevas Capturas de Pantalla

Aquí hay algunas sugerencias para crear capturas de pantalla nuevas y atractivas. Las imágenes deben colocarse en una carpeta de imágenes (img/) que se encuentra en la misma carpeta que el archivo de referencia .rst.

  • Puede encontrar algunos proyectos QGIS preparados que se utilizan para crear capturas de pantalla en la carpeta: file: . / Qgis-projects de este repositorio. Esto facilita la reproducción de capturas de pantalla para la próxima versión de QGIS. Estos proyectos utilizan QGIS Sample Data (aka Alaska Dataset), que debe colocarse en la misma carpeta que el repositorio de documentación de QGIS.

  • Reduzca la ventana al espacio mínimo necesario para mostrar la función (tomando toda la pantalla para una pequeña ventana modal> exageración)

  • Cuanto menos desorden, mejor (no es necesario activar todas las barras de herramientas)

  • No los cambie de tamaño en un editor de imágenes; el tamaño se establecerá en los archivos .rst si es necesario (reduciendo las dimensiones sin aumentar adecuadamente la resolución> feo)

  • Cortar el fondo

  • Haga transparentes las esquinas superiores si el fondo no es blanco

  • Establezca la resolución del tamaño de impresión en `` 135 ppp “” (por ejemplo, en Gimp configure la resolución de impresión Imagen -> tamaño de impresión y guarde). De esta forma, las imágenes estarán en tamaño original en html y con una buena resolución de impresión en el PDF. También puede usar el comando de conversión de ImageMagick para hacer un lote de imágenes:

    convert -units PixelsPerInch input.png -density 135 output.png

  • Guárdelos como .png (para evitar artefactos .jpeg)

  • La captura de pantalla debe mostrar el contenido de acuerdo con lo que se describe en el texto.

Truco

Si está en Ubuntu, puede usar el siguiente comando para eliminar la función del menú global y crear pantallas de aplicaciones más pequeñas con menús:

sudo apt autoremove appmenu-gtk appmenu-gtk3 appmenu-qt

2.2.2. Capturas de Pantalla Traducidas

Aquí hay algunas sugerencias adicionales para aquellos que desean crear capturas de pantalla para una guía de usuario traducida:

las imágenes trasladadas deben ser ubicadas en la carpeta img/<your_language>/. Utilice el mismo nombre de archivo que la captura de pantalla “original” en inglés.

2.3. Documentando algoritmos de Procesamiento

Si desea escribir documentación para los algoritmos de procesamiento, tenga en cuenta estas pautas:

  • Los archivos de ayuda del algoritmo de procesamiento son parte de la Guía del usuario de QGIS, así que use el mismo formato que la Guía del usuario y otra documentación.

  • La documentación de cada algoritmo debe colocarse en la carpeta proveedor y el archivo grupo correspondientes, p. Ej. el algoritmo Voronoi polygon pertenece al proveedor` QGIS` y al grupo vectorgeometry. Entonces, el archivo correcto para agregar la descripción es: source/docs/user_manual/processing_algs/qgis/vectorgeometry.rst.

    Nota

    Antes de comenzar a escribir la guía, verifique si el algoritmo ya está descrito. En este caso, puede mejorar la descripción existente.

  • Es extremadamente importante que cada algoritmo tenga un vínculo que corresponda al nombre del proveedor + el nombre único del algoritmo en sí. Esto permite que el botón Ayuda abra la página de Ayuda de la sección correcta. El ancla debe colocarse encima del título, p. Ej. (ver también la sección Etiquetas/referencias ):

    .. _qgisvoronoipolygons:

Voronoi polygons
----------------

    Para averiguar el nombre del algoritmo, simplemente coloque el mouse sobre el algoritmo en la caja de herramientas de Procesamiento.

  • Evite utilizar «Este algoritmo hace esto y aquello …» como la primera oración en la descripción del algoritmo. Intente usar expresiones más generales como:

    Takes a point layer and generates a polygon layer containing the...

  • Evite describir lo que hace el algoritmo replicando su nombre y no repita el nombre del parámetro en la descripción del parámetro en sí. Por ejemplo, si el algoritmo es Polígono de Voronoi, considere la posibilidad de describir la Capa de entrada como Capa desde la que calcular el polígono.

  • Indique en la descripción si el algoritmo tiene un acceso directo predeterminado en QGIS o admite la edición in situ.

  • ¡Añadir imágenes! ¡Una imagen vale mas que mil palabras! Utilice el formato .png y siga las pautas generales para la documentación (consulte la sección Figuras e Imágenes para obtener más información). Coloque el archivo de imagen en la carpeta correcta, es decir, la carpeta img junto al .rst que está editando.

  • Si es necesario, agregue enlaces en la sección «Ver también» que brinden información adicional sobre el algoritmo (por ejemplo, publicaciones o páginas web). Solo agregue la sección «Ver también» si realmente hay algo que ver. Como buena práctica, la sección «Ver también» puede llenarse con enlaces a algoritmos similares.

  • Dé una explicación clara de los parámetros y resultados de los algoritmos: inspírese en los algoritmos existentes.

  • Evite duplicar la descripción detallada de las opciones del algoritmo. Agregue esta información en la descripción del parámetro.

  • Evite agregar información sobre el tipo de geometría vectorial en el algoritmo o la descripción del parámetro, ya que esta información ya está disponible en las descripciones de los parámetros.

  • Agregue el valor predeterminado del parámetro, por ejemplo:

    * - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [number]

    Default: 1
  - Number of points to create

  • Describe el tipo de entrada compatible con los parámetros. Hay varios tipos disponibles entre los que puede elegir:

    Tipo de Parámetro/Salida

    Descripción

    Indicador visual

    Capa vectorial punto

    vector: point

    pointLayer

    Capa vectorial línea

    vector: line

    lineLayer

    Capa vectorial poligonal

    vector: polygon

    polygonLayer

    Capa vectorial genérica

    vector: any

    Campo vectorial numérico

    tablefield: numeric

    fieldFloat

    Campo vectorial cadena

    tablefield: string

    fieldText

    Campo vectorial genérico

    tablefield: any

    Capa ráster

    raster

    rasterLayer

    Banda ráster

    raster band

    Archivo HTML

    html

    Capa tabla

    table

    tableLayer

    Expresión

    expression

    expression

    Geometría punto

    coordinates

    Extensión

    extent

    SRC

    crs

    setProjection

    Enumeración

    enumeration

    selectString

    Lista

    list

    NUmero

    number

    selectNumber

    Cadena

    string

    inputText

    Booleano

    boolean

    checkbox

    Ruta de carpeta

    folder

    Archivo

    file

    Matriz

    matrix

    Capa

    layer

    Mismo tipo de salida que tipo de entrada

    same as input

    Definición

    definition

    Punto

    point

    MultipleLayers

    multipleLayers

    Intervalo

    range

    AuthConfig

    authconfig

    Malla

    mesh

    Diseño

    layout

    Elemento de diseño

    layoutitem

    Color

    color

    Escala

    scale

  • Estudie un algoritmo existente y bien documentado y copie todos los diseños útiles.

  • Cuando haya terminado, simplemente siga las pautas descritas en Una contribución paso a paso para confirmar sus cambios y hacer una Pull Request

Aquí hay un ejemplo de existing algorithm para ayudarte con el diseño y la descripción:

.. _qgiscountpointsinpolygon:

Count points in polygon
-----------------------
Takes a point and a polygon layer and counts the number of points from the
point layer in each of the polygons of the polygon layer.
A new polygon layer is generated, with the exact same content as the input
polygon layer, but containing an additional field with the points count
corresponding to each polygon.

.. figure:: img/count_points_polygon.png
  :align: center

  The labels in the polygons show the point count

An optional weight field can be used to assign weights to each point.
Alternatively, a unique class field can be specified. If both options
are used, the weight field will take precedence and the unique class field
will be ignored.

``Default menu``: :menuselection:`Vector --> Analysis Tools`

Parameters
..........

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Label
     - Name
     - Type
     - Description
   * - **Polygons**
     - ``POLYGONS``
     - [vector: polygon]
     - Polygon layer whose features are associated with the count of
       points they contain
   * - **Points**
     - ``POINTS``
     - [vector: point]
     - Point layer with features to count
   * - **Weight field**

       Optional
     - ``WEIGHT``
     - [tablefield: numeric]
     - A field from the point layer.
       The count generated will be the sum of the weight field of the
       points contained by the polygon.
   * - **Class field**

       Optional
     - ``CLASSFIELD``
     - [tablefield: any]
     - Points are classified based on the selected attribute and if
       several points with the same attribute value are within the
       polygon, only one of them is counted.
       The final count of the points in a polygon is, therefore, the
       count of different classes that are found in it.
   * - **Count field name**
     - ``FIELD``
     - [string]

       Default: 'NUMPOINTS'
     - The name of the field to store the count of points
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]

       Default: [Create temporary layer]
     - Specification of the output layer type (temporary, file,
       GeoPackage or PostGIS table).
       Encoding can also be specified.

Outputs
.......

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Label
     - Name
     - Type
     - Description
   * - **Count**
     - ``OUTPUT``
     - [vector: polygon]
     - Resulting layer with the attribute table containing the
       new column with the points count