Importante

La traducción es un esfuerzo comunitario puede unirse. Esta página está actualmente traducida en |progreso de traducción|.

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»

Sections used to structure the text are identified through their title which is underlined (and overlined for the first level). Same level titles must use same character for underline adornment. Precede section titles with a blank line. In QGIS Documentation, you should use following styles for chapter, section, subsection and 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. Indentación

Indentation in reStructuredText should be aligned with the list or markup marker. It is also possible to create block quotes with indentation. See the Specification

#. In a numbered list, there should be
   three spaces when you break lines
#. And next items directly follow

   * Nested lists
   * Are also possible
   * And when they also have
     a line that is too long,
     the text should be naturally
     aligned
   * and be in their own paragraph

However, if there is an unindented paragraph, this will reset the numbering:

#. This item starts at 1 again

2.1.4. 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``

  • Layers, databases, tables or columns names

    When referring to layers, databases, tables or columns, format as inline code:

    ``layer name``
``database_name``
``table_name``
``column_name``

2.1.5. 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.6. Figuras e Imágenes

Imágenes

Para insertar una imagen, use

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

Que devolverá

../../_images/logo.png

Icon substitution

You can add an image inside a text paragraph (e.g., as a tool icon). To do so, you first need to create an alias (also named substitution), which is a reference name used to display the icon. To ensure consistency across the documents and help in the use of the icons, we maintain a list in the substitutions.txt file at the root of this repository. Find more details in the Sustituciones chapter.

Using an icon substitution is usually achieved through these steps:

  1. Add the icon substitution in the substitutions.txt file as below. If a substitution already exists for the icon you want to use, then skip this step.

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

  2. Call it in your paragraph:

    My paragraph begins here with |logo|.

  3. Add (again) the icon substitution at the end of the file you are modifying. This helps connecting the replacement text with the actual image, and can be done by copy-pasting it from substitutions.txt or by executing the scripts/find_set_subst.py script.

    Así es como se mostrará el ejemplo:

    My paragraph begins here with logo.

Figura

.. _figure_logo:

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

   A caption: A logo I like

El resultado se parece a esto:

../../_images/logo.png

Figura 2.24 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.24

Este es el modo prefereido de referenciar figuras.

Nota

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

Es posible usar :ref: en lugar de :numref: como referencia, pero esto devuelve el título completo de la imagen.

see :ref:`figure_logo`

se representa como esto:

ver:ref:figure_logo

2.1.7. Tablas

You can make a simple table like this:

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

Se representará como esto:

x

y

z

1

2

3

4

5

Tables should have a caption. You can use an explicit reST «table» directive to add a caption to simple tables or grid tables. Add the caption on the same line as the directive and indent the table at least one space.

You can also add a hyperlink target before a table in order to reference it elsewhere. To avoid conflicts with other references, always begin hyperlink targets with _table_ and use terms relevant to the table caption.

Here is an example of a more complicated grid table with a caption and a hyperlink target:

.. _table-grid-caption:

.. table:: Grid table with caption

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

El resultado:

Tabla 2.2 Grid table with caption

Windows

macOS

win

osx

y por supuesto no olviden nix

You may find it easier to use list tables or CSV tables to make complex tables. Add the caption after the list-table or csv-table directive.

Here is an example of a list table with a caption and a hyperlink target:

.. _table-list-caption:

.. list-table:: List table with caption
   :header-rows: 1
   :widths: 20 20 20 40

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

       * Point
       * Line

El resultado:

Tabla 2.3 List table with caption

Que

Propósito

Palabra clave

Descripción

Probar

Useful test

complejidad

Geometría. Una de:

  • Punto

  • Línea

Use :numref: roles to reference tables like this:

see :numref:`table-grid-caption` or :numref:`table-list-caption`

El resultado:

Nota

You must add a caption to your table in order to create a cross reference with the :numref: role.

2.1.8. Index

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.

Several index tags exist in reST. You can use the inline :index: tag within normal text:

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

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.9. Comentarios Especiales

En ocasiones, es posible que desee resaltar 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:: y . tip::. Estas directivas generan marcos que resaltan sus comentarios. Consulte Marcado a nivel de párrafo para obtener más información. Se requiere un título claro y adecuado tanto para las advertencias como para los consejos.

.. 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.10. 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

Text in special comments will be translated, but text in code-block frames will not be translated. So keep comments in code blocks as short as possible and avoid comments unrelated to code.

2.1.11. Notas al pie

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

blabla [1]_

Que apuntará a:

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.

  • You can find some prepared QGIS projects that are used to create screenshots in the ./qgis-projects folder of this repository. This makes it easier to reproduce screenshots for the next version of QGIS. These projects use the QGIS Sample Data (aka Alaska Dataset), which should be unzipped and placed in the same folder as the QGIS-Documentation Repository.

  • 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

  • Set print size resolution to 135 dpi (e.g., in GIMP scale down the image using Image ► Scale Image and setting «X/Y» to 135 pixels/in, and export it through File ► Export…). This way, images will be at original size in HTML and at a good print resolution in the PDF.

    También puede utilizar el comando convert de ImageMagick para procesar 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:

Translated images should be placed in a img/<your_language>/ folder. Use the same filename as the “original” English screenshot.

2.3. Documentando algoritmos de Procesamiento

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

  • Processing algorithm help files are part of QGIS User Guide, so use the same formatting as the User Guide and other documentation.

  • 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.

  • It is extremely important that each algorithm has an anchor that corresponds to the provider name + the unique name of the algorithm itself. This allows the Help button to open the Help page of the correct section. The anchor should be placed above the title, e.g. (see also the Etiquetas/referencias section):

    .. _qgisvoronoipolygons:

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

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

  • Avoid using «This algorithm does this and that…» as the first sentence in the algorithm description. Try to use more general expressions like:

    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.

  • Add the default value of the parameter, e.g.:

    * - **Number of points**
  - ``NUMBER_OF_POINTS``
  - [numeric: integer]

    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

    Todas las capas vectoriales espaciales

    vector: geometry

    Capa vectorial sin geometría

    vector: table

    tableLayer

    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

    Expresión

    expression

    expression

    Line geometry

    geometry: line

    Geometría punto

    coordinates

    Extensión

    extent

    CRS

    crs

    setProjection

    Enumeración

    enumeration

    selectString

    Lista

    list

    Valor entero

    numeric: integer

    selectNumber

    Valor decimal

    numeric: double

    selectNumber

    Cadena

    string

    inputText

    Boolean

    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

    Capas del mapa

    layer list

    Rango

    range

    AuthConfig

    authconfig

    Malla

    mesh

    Diseño

    layout

    Elemento de diseño

    layoutitem

    Color

    color

    Escala

    scale

    Tema del mapa

    tema del mapa

  • 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

Here is an example of an existing algorithm to help you with the layout and the description:

.. _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
   :class: longtable

   * - 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