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:

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).
Acercar al máximo nivel de zoom (mantener NumpadMás o Ctrl-ClickCentral o similar).
Alejar ocho niveles de zoom (NumpadMenos – ocho veces).
In some cases you will want to leave a small margin around the thing you are trying to capture. This should be around 30px but does not have to be exact.

This can be applied to several parts of the interface but might not work for all cases.

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 for images that have solid colors such as screenshots of the Blender interface, and .jpg for images with a high amount of color variance, such as sample renders and photographs.

Do not use animated .gif files, these are hard to maintain, can be distracting and are usually large in file size. Instead use a video if needed (see Videos below).

Ubicación

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

Nombrado

For naming files use underscores to separate chapters and sections, and use dashes to separate sections that are two or more words. So for image files should look like: chapter_subsection_sub-subsection_id.png, e.g:

interface_splash_current.png
interface_undo-redo_last.png
interface_undo-redo_repeat-history-menu.png

Do not use special characters or spaces!

Guías de uso¶

Avoid specifying the resolution of the image, so that the theme can handle the images consistently and provide the best layout across different screen sizes.
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).