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.

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

Otras convenciones menores:

  • Evitar caracteres Unicode.

  • Evitar el texto muy enrevesado (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 sólo debería tener un encabezado de capitulo (*) por archivo.

Estilo del Texto#

Ver el resumen de ReStructuredText para más información sobre el estilo de los diversos elementos de la documentación y cómo agregar listas, tablas, imágenes y bloques de código. La referencia de Sphinx proporciona más información sobre estructuras adicionales.

Las siguientes son marcados útiles para estilizar texto:

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

Elementos de la Interfaz#

  • :kbd:`LMB` - atajos de teclado y de ratón.

  • *Espejo* - etiquetas de interfaz.

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

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/interface_window-system_splash_current.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. Preparar el área que se desee capturar y asegurarse de usar el tema y los ajustes predefinidos. (En algunos casos, es posible que no se desee utilizar la configuración predefinida, por ejemplo, cuando algunas opciones se encuentren ocultas detrás de una casilla de verificación).

  2. Amplía hasta el máximo nivel de acercamiento (mantener + numérico o Ctrl-MMB o similar).

  3. Reduce ocho niveles la ampliación (- numérico – 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

Usar .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 una gran variación de color, tales como imágenes procesadas 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).

Posición

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

Nomenclatura

Para nombrar archivos, utilizar guiones bajos para separar capítulos y secciones, y utilizar guiones para separar secciones que sean de dos o más palabras. Así que para los archivos de imagen debería verse así: “”capítulo_subsección_sub-subsección_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 documente un panel o sección de la interfaz de usuario, será mejor usar una única imagen que muestre todo acerca de las áreas relevantes (en lugar de varias imágenes para cada ícono o botón) ubicada en la parte superior de la sección que se esté escribiendo, y luego, 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 se pueden anexarse desde la instancia auto-hospedada PeerTube de Blender, que se puede encontrar en video.blender.org. Para anexar un video usando la siguiente directiva:

.. peertube:: ID

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

El ID de https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c es 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

Para subir un nuevo video, comuníquese con un Administrador del Proyecto de Documentación o incluya el video subido en su descripción de Solicitud de Incorporación de Cambios.

Guías de uso#

  • Evite agregar videos que dependan de la voz o las palabras, ya que esto es difícil de traducir.

  • No embeba tutoriales en video como un medio para explicar una característica, la escritura en sí debe explicarla adecuadamente. (Aunque puede incluir un enlace al video en la parte inferior de la página bajo el título Tutoriales).

Construcciones Útiles#

  • |BLENDER_VERSION| - Referirá a la versión actual de Blender.

  • :abbr:`SSAO (Screen Space Ambient Occlusion u Oclusión ambiental en espacio de pantalla)` - Las abreviaturas mostrarán el texto completo en forma de descripción emergente, para el lector.

  • :term:`Desplegable` - 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>`__

Manual de Acceso a Contexto Sensitivo#

Es posible vincular a una parte específica del manual desde Blender abriendo el menú contextual (clic derecho) de una propiedad u operador y seleccionando Manual en línea. Para que esto funcione, esto debe tenerse en cuenta en la documentación. Para vincular una propiedad u operador a una parte específica del manual, debe agregar una etiqueta de enlace de referencia externa cuya identificación coincida con la etiqueta de ARN de Blender. La forma más sencilla de averiguar cuál es la etiqueta de una propiedad es abrir el menú contextual de la propiedad/operador y seleccionar Referencia de Python en línea para extraer la etiqueta de la URL. Algunos ejemplos de cómo se ve esto en el documento RST se dan a continuación:

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

Para un operador:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Lecturas adicionales#

Para aprender más acerca de reStructuredText, mirar:

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.