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.
Usar 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).

Títulos¶

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

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

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

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

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

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

Nota

Las partes sólo deberían ser usadas para el contenido o páginas de índice.

Nota

Cada archivo .rst sólo debería tener un título 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 proporcionará 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 ratón.
*Espejo* – etiquetas de la interfaz.
:menuselection:`Vista 3D --> Agregar --> Malla --> Mono` – menús.

Muestras de código¶

Existe soporte para el resaltado de sintaxis, en caso de que el lenguaje de programación sea provisto, y los números de línea podrán ser mostrados opcionalmente, mediante la opción :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Reservar nombres¶

If information needs to be added in the future, do not simply add a paragraph saying «to-do» or «will add later.» Instead, use proper markup with the keyword. This will be visible to the end-user in a special block:

.. todo:: message goes here

If you intend to add a placeholder that should NOT be visible to the end user, use the syntax:

.. TODO internal developer message goes here

Note that the lowercase keyword with 2 colons will render in the page while the uppercase keyword without colons will not.

Imágenes¶

Deberían usarse Figuras para colocar imágenes:

.. figure:: /images/interface_window-system_splash_current.png

   Image caption.

Para lograr una mayor consistencia (y puesto que sería bueno asegurar que todas las capturas de pantalla tuvieran un tamaño similar cuando sean presentadas al lado de textos), los escritores deberían tomar capturas de pantalla de la siguiente forma:

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).
Ampliar hasta el máximo nivel de acercamiento (mantener + numérico o Ctrl-MMB o similar).
Reducir el nivel de ampliación ocho niveles (- numérico – ocho veces).
En algunos casos será bueno dejar un pequeño margen alrededor de lo que se esté tratando de capturar. Uno de alrededor de 30px estará bien, aunque no tiene por qué ser algo exacto.

Será posible aplicar esto a varias partes de la interfaz, aunque 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 una manera útil

Ordenar la nomenclatura usando identificadores específicos al final.

Formato

Usar el formato .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 usar el formato .gif animado, estas imágenes son difíciles de mantener, podrían generar distracciones, además de que usualmente resultarán de tamaño muy grandes. En su lugar, será preferible utilizar un video en caso de ser necesario (ver Videos más abajo).

Posición

Ubicar la imagen en la carpeta manual/images. No utilizar 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 se deberán usar 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 suelen cambiar, por lo que se deberá intentar evitar tener muchas imágenes (cuando éstas no sean especialmente necesarias). De lo contrario, se volverá demasiado complicado de mantener.

Videos¶

Los videos podrán ser incorporados desde la instancia auto-hospedada PeerTube de Blender, que podrá ser encontrada en video.blender.org. Para incorporar un video se deberá usar la siguiente directiva:

.. peertube:: ID

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

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

Para poder subir un nuevo video, será necesario contactarse con un Administrador del proyecto de documentación o incluir el video a ser subido en la descripción de la Solicitud de incorporación de cambios.

Guías de uso¶

Se deberá evitar agregar videos que dependan de la voz o palabras, ya que esto resultará menos útil en las versiones traducidas del manual.
No se deberán incorporar videos como forma de explicar características, la parte escrita del manual deberá explicarla adecuadamente. (De todas maneras podrá incluirse un enlace al video, en la parte inferior de la página bajo el título Tutoriales).

Estructuras ú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¶

Será posible enlazar a otro documento en el manual mediante:

: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>`

Enlace a un título en el mismo archivo:

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

Body text.

Implicit references, like `Titles are Targets`_

Enlace al mundo exterior:

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

Acceso al manual según el contexto¶

Será 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 deberá tenerse en cuenta en la documentación. Para vincular una propiedad u operador a una parte específica del manual, se deberá agregar una etiqueta de enlace de referencia externa, cuya identificación coincida con la etiqueta RNA 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 u operador y seleccionar Referencia en línea de Python para extraer la etiqueta de la URL. A continuación se proporcionan ejemplos de cómo se verá esto en el documento RST:

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

Íconos¶

Los íconos de Blender podrán ser incluidos como parte del texto, usando:

`:bl-icon:`<icon_name>`

Lecturas adicionales¶

Para aprender más acerca de reStructuredText, ver:

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.