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 menores a 120 caracteres de longitud.

  • Use itálicas para nombres de botones y menús.

Otras convenciones menores:

  • Evite caracteres Unicode.

  • Evite el texto muy ajustado (ej. las oraciones pueden tener sus propias líneas).

Encabezados

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

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

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

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

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

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

Nota

Las Partes solo deben usarse para contenidos o páginas de índice.

Nota

Cada archivo .rst solo debe tener un encabezado de capitulo (*) por archivo.

Estilo de Texto

Vea un resumen de ReStructuredText (en inglés) para más información sobre cómo estilizar 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 (en inglés) proporciona más información sobre formas adicionales.

Las siguientes son estilo de texto útiles:

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

Elementos de la Interfaz

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

  • *Espejar* - etiquetas de interfaz.

  • :menuselection:`3D View --> Add --> Mesh --> Monkey` - menús.

Muestras de código

Hay asistencia para el resaltado de sintaxis si se proporciona el lenguaje de programación, 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

Los Figures se usan para colocar imágenes:

.. figure:: /images/render_cycles_nodes_types_shaders_node.png

   Image caption.

Para la consistencia, y como debería de asegurarse de que las capturas de pantalla tengan un tamaño similar cuando se coloque junto al texto, los escritores deben tomar capturas de pantalla de la siguiente manera:

  1. Prepare el área que desea capturar y asegúrese de usar el tema y la configuración 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 verificación).

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

  3. Alejar 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 debe ser 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 Capitalización, 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

Use .png para las imágenes que tienen colores sólidos tales como capturas de pantalla de la interfaz de Blender, y .jpg para 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 ser muy distractores y usualmente son muy grandes en tamaño. Si se necesita un video, utilice YouTube o Vimeo (vea Videos más abajo).

Ubicación

Ubique la imagen en la carpeta manual/images. No utilice otras subcarpetas.

Nombrado

Para la nomenclatura de los archivos, utilice guiones bajos para separar capítulos y secciones y utilice guiones para separar secciones que son dos o más palabras. Así que para los archivos de imagen debe tener el siguiente aspecto: “”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 use caracteres especiales o espacios!

Guías de uso

  • Evite especificar la resolución de la imagen, de modo que el tema pueda manejar las imágenes de forma coherente y proporcionar el mejor diseño en diferentes tamaños de pantalla.

  • When documenting a panel or section of the UI, it is better to use a single image that shows all of the relevant areas (rather than multiple images for each icon or button) placed at the top of the section you are writing, and then explain the features in the order that they appear in the image.

    Nota

    Es importante que el manual se pueda mantener a largo plazo, las opciones de herramientas y la Interfaz de Usuario cambian, así que evite tener muchas imágenes (cuando estas no son especialmente necesarias). De lo contrario, esto se vuelve demasiado complicado de mantener.

Videos

Videos from YouTube™ and Vimeo™ can be embedded using:

.. youtube:: ID

.. vimeo:: ID

El ID se encuentra en la URL del video, ej:

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

  • El ID para https://vimeo.com/15837189 es 15837189

Guías de uso

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

  • No embeba video tutoriales con el objetivo de explicar una característica, la escritura por sí misma debería explicarlo adecuadamente (aunque puede incluir enlaces a un video en la zona inferior de la página bajo el título Tutoriales).

Constructores Útiles

  • |BLENDER_VERSION| – Resolves to the current Blender version.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – Abbreviations display the full text as a tooltip for the reader.

  • :term:`Manifold` – Links to an entry in the Glossary.

Referencias cruzadas y Enlaces

You can link to another document in the manual with:

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

To link to a specific section in another document (or the same one), explicit labels are available:

.. _sample-label:

[section or image to reference]

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

Linking to a title in the same file:

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

Body text.

Implicit references, like `Titles are Targets`_

Linking to the outside world:

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

Directory Layout

Las secciones generalmente se deberían estructurar como sigue:

  • nombre_de_directorio/

    • index.rst (contiene enlaces a archivos internos)

    • introduccion.rst

    • seccion_1.rst

    • seccion_2.rst

Por ejemplo:

  • renderizado/

    • index.rst

    • cycles/

      • index.rst

      • introduccion.rst

      • materiales/

        • index.rst

        • introduccion.rst

        • volumenes.rst

The idea is to enclose all the content of a section inside of a folder. Ideally every section should have an index.rst (containing the TOC for that section) and an introduction.rst (introducing) to the contents of the section.

Tabla de Contenidos

By default, a table of contents should show two levels of depth:

.. toctree::
   :maxdepth: 2

   introduction.rst
   perspective.rst
   depth_of_field.rst

Lecturas adicionales

Para aprender más acerca de reStructuredText, vea:

Manual de Sphinx RST (en inglés)

Buena introducción básica.

Referencia a las utilidades de la documentación de reStructuredText

Enlaces a referencias y documentación de usuario (en inglés).