Guía de Estilo de Marcado

Esta página cubre las convenciones para la escritura y el uso de la sintaxis de marcado reStructuredText (RST).

Convenciones

  • Sangría de tres espacios.

  • Las líneas deberían ser de menos de 120 caracteres de longitud.

  • Usa cursiva para nombres de botones y menús.

Otras convenciones menores:

  • Evitar caracteres Unicode.

  • Evitar el texto muy apretado (por ejemplo, las oraciones pueden tener sus propias líneas).

Encabezados

#################
  Document Part
#################

****************
Document Chapter
****************

Document Section
================

Document Subsection
-------------------

Document Subsubsection
^^^^^^^^^^^^^^^^^^^^^^

Document Paragraph
""""""""""""""""""

Nota

Las Partes sólo deberían ser usadas para contenidos o páginas de índices.

Nota

Cada archivo .rst solo debería tener un encabezado de capitulo (*) por archivo.

Estilo del Texto

Véase el resumen de ReStructuredText para más información sobre el estilo de los diversos elementos de la documentación y cómo añadir listas, tablas, imágenes y bloques de código. La referencia de Sphinx proporciona más información sobre construcciones adicionales.

Las siguientes son marcados útiles para estilizar texto:

*italic*
**bold**
``literal``

Elementos de la Interfaz

  • :kbd:`LMB` - atajos de teclado y del mouse.

  • *Espejo* - etiquetas de interfaz.

  • :menuselection:`Vista 3D --> Agregar --> Malla --> Mono` - menús.

Operator Menus

Each operator should receive its own heading or page based on the length of the content. Each operator should have a reference admonition documenting the context of the operator:

.. admonition:: Reference
   :class: refbox

   :Mode:      Edit Mode
   :Menu:      :menuselection:`Curve --> Snap`
   :Hotkey:    :kbd:`Shift-S`

Panels

Panels should be documented by their own heading, nested panels should use decreasing heading levels. Each panel could have its own page based on the length of documentation and/or the amount of panels. Expanded menus that toggle what properties are presented to the user should be treated like subpanels:

Panel Title
===========

Nested Panel Title
------------------

Properties

Properties should be documented using definition lists. Properties that are hidden based on other properties should used nested definitions:

Property
   Property description.

   Hidden Property
      Hidden property description.

Enum based menus should be documented using the following syntax:

Menu Label
   General description of the menu.

   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.
   :Menu Item: Menu Item Definition.

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by right clicking on a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to right click on the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid / obstacle regions (second order obstacles)...

   .. _bpy.types.FluidDomainSettings.fractions_distance:

   Obstacle Distance
      Determines how far apart fluid and obstacles are...

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Muestras de código

Hay asistencia para el resaltado de sintaxis si el lenguaje de programación es provisto, y los números de línea se pueden mostrar opcionalmente con la opción :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Imágenes

Figure debería ser usado para colocar imágenes:

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

Para la consistencia, y puesto que sería bueno para asegurar que todas las capturas de pantalla tengan un tamaño similar cuando son presentadas al lado del texto, los escritores deberían tomar capturas de pantalla de la siguiente forma:

  1. Prepara el área que te gustaría capturar y asegúrate de usar el tema y los ajustes por defecto. (En algunos casos, es posible que no desee utilizar la configuración por defecto, por ejemplo, si algunas opciones están ocultas detrás de una casilla de control).

  2. Acerca al máximo nivel de zoom (mantener NumpadMás o Ctrl-ClickCentral o similar).

  3. Aleja ocho niveles de zoom (NumpadMenos – ocho veces).

  4. En algunos casos querrás dejar un pequeño margen alrededor de lo que estás tratando de capturar. Esto debería ser de alrededor de 30px pero no tiene que ser exacto.

Esto se puede aplicar a varias partes de la interfaz, pero es posible que no funcione para todos los casos.

Archivos

Sin Mayúsculas, Sin Espacios

Nombres de archivo en minúsculas y guiones bajos entre las palabras.

Ordenar de forma útil

Orden de nombrado con identificadores específicos al final.

Formato

Usa .png para las imágenes que tengan colores sólidos tales como capturas de pantalla de la interfaz de Blender, y .jpg para las imágenes con muchas variaciones de color, tales como renders de muestra y fotografías.

No use archivos .gif animados, estos son difíciles de mantener, pueden generar distracciones y usualmente son muy grandes en tamaño. En su lugar, utiliza un video de ser necesario (ve Videos abajo).

Ubicación

Ubica la imagen en la carpeta manual/images. No utilices otras subcarpetas.

Nombrado

Para nombrar archivos, utiliza guiones bajos para separar capítulos y secciones, y utiliza guiones para separar secciones que sean de dos o más palabras. Así que para los archivos de imagen debería verse así: “”chapter_subsection_sub-subsection_id.png””, por ejemplo:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

¡No uses caracteres especiales o espacios!

Guías de Uso

  • Evita especificar la resolución de la imagen, de modo que el tema pueda manejar las imágenes de forma consistente y proveer el mejor diseño a través de diferentes tamaños de pantalla.

  • Cuando se documenta un panel o sección de la Interfaz de Usuario, es mejor usar una única imagen que muestre todo acerca de las áreas relevantes (en lugar de varias imágenes para cada icono o botón) ubicada sobre la sección que estás escribiendo, y entonces, explicar las características en el mismo orden en que aparecen en la imagen.

    Nota

    Es importante que el manual pueda ser mantenido a largo plazo, las opciones de herramientas y de la Interfaz de Usuario cambian, así que intenta evitar tener muchas imágenes (cuando éstas no sean especialmente necesarias). De lo contrario, esto se vuelve demasiado complicado para mantener.

Videos

Los videos de YouTube™ pueden ser embebidos usando:

.. youtube:: ID

El ID se encuentra en la URL del video, por ejemplo:

El ID para https://www.youtube.com/watch?v=Ge2Kwy5EGE0 es Ge2Kwy5EGE0.

Guías de Uso

  • Evita agregar videos que dependan de la voz, ya que esto es difícil de traducir.

  • No embebas video tutoriales con el objetivo de explicar una característica, la escritura por sí misma debería explicarlo adecuadamente (aunque puedes incluir enlaces al video en la parte inferior de la página debajo del encabezado Tutoriales).

Construcciones Útiles

  • |BLENDER_VERSION| - Se refiere a la versión actual de Blender.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` - Las abreviaciones muestran el texto completo como un tooltip para el lector.

  • :term:`Manifold` - Enlaza a una entrada en el Glosario.

Referencias cruzadas y Enlaces

Puedes enlazar a otro documento en el manual con:

:doc:`The Title </section/path/to/file>`

Para enlazar a una sección específica en otro documento (o el mismo), hay disponibles unas etiquetas explícitas:

.. _sample-label:

[section or image to reference]

Some text :ref:`Optional Title <sample-label>`

Enlazando a un título en el mismo archivo:

Titles are Targets
==================

Body text.

Implicit references, like `Titles are Targets`_

Enlazando al mundo exterior:

`Blender Website <https://www.blender.org>`__

Disposición del Directorio

Las secciones generalmente deberían ser estructuradas como sigue:

  • directory_name/

    • index.rst (contiene enlaces a archivos internos)

    • introduccion.rst

    • seccion_1.rst

    • seccion_2.rst

Por ejemplo:

  • rendering/

    • index.rst

    • cycles/

      • index.rst

      • introduccion.rst

      • materials/

        • index.rst

        • introduccion.rst

        • volumenes.rst

La idea es meter todo el contenido de una sección dentro de una carpeta. Idealmente cada sección debería tener un index.rst (conteniendo el TOC para esa sección) y un introduction.rst a los contenidos de la sección.

Tabla de Contenidos

Por defecto, una tabla de contenidos debería mostrar dos niveles de profundidad:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Lecturas Adicionales

Para aprender más acerca de reStructuredText, mira:

Manual Básico de Sphinx RST

Buena introducción básica.

Referencia a los Docutils de reStructuredText

Enlaces a la referencia y a la documentación de usuario.