Guia d’estils de marcat

Aquesta pàgina cobreix les convencions per escriure i utilitzar la sintaxi de marcatge reStructuredText (RST).

Convencions

  • Sagnat de tres espais.

  • Les línies haurien de tenir menys de 120 caràcters.

  • Utilitzar cursiva per als noms dels botons/menú.

Altres convencions:

  • Evitar els caràcters Unicode.

  • Eviteu el text molt embolicat (és a dir, les frases poden tenir les seves pròpies línies).

Encapçalaments

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

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

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

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

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

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

Nota

Les parts només s’han d’utilitzar per a continguts o pàgines d’índex.

Nota

Cada document .rst només hauria de tenir un encapçalament de capítol (*) per document.

Estil del text

Vegeu la visió general de ReStructuredText per a més informació sobre com associar estils als diferents elements de la documentació i sobre com afegir llistes, taules, imatges i blocs de codi. La Referencia de Sphinx ofereix més constructes addicionals amb aclariments.

Elements utils per al marcatge d’estils de text:

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

Elements de la interficie

  • :kbd:`BER` – dreceres de ratolí i teclat.

  • *Mirror* – etiques d’interficie.

  • :menuselection:`Vista 3D -> Afegir --> Malla --> Monkey` – menus.

Exemples de codi

Existeix suport per al ressaltat de sintaxi si s’aporta el llenguatge de programació, i els números de línia es poden mostrar opcionalment amb l’opció :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Imatges

Per emplaçar imatges s’han d’emprar figures:

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

   Image caption.

Per coherència i per assegurar-se que les captures de pantalla són totes d’una mida similar quan es col·loquen al costat del text,els escriptors haurien de prendre captures de pantalla de la manera següent:

  1. Preparar l’àrea que voleu capturar assegurant-vos d’utilitzar el valors predeterminats per al tema i configuració. (En alguns casos és possible que no vulgueu utilitzar la configuració predeterminada, per exemple, si algunes opcions s’amaguen darrere d’una casella de selecció.)

  2. Amplia fins al nivell de zoom màxim (prem NumpadPlus o Ctrl-BMR o similar).

  3. Redueix vuit nivells de zoom (NumpadMinus – vuit vegades).

  4. En alguns casos, voldreu deixar un petit marge al voltant del que voleu capturar. Hauria de ser d’uns 30 píxels, però no ha de ser exacte.

Això es pot aplicar a diverses parts de la interfície, però pot ser que no funcioni per a tots els casos.

Documents

Sense Majúscules, Sense Espais

Nom dels documents en minúscules amb guionet baix entre paraules.

Ordena de manera útil

Ordena els noms amb el identificados específics al final.

Format

Utilitza .png per imatges amb colors solids, com captures de pantalla de la interfície del Blender, i .jpg per imatges amb una alta variació de color com revelats i fotografies.

No utilitzar arxius animats .gif, són difícils de mantenir, poden provocar distraccions i normalment son grans de tamany. Com alternativa utilitzeu un video (vegeu Videos més abaix).

Ubicació

Situeu la imatge en la carpeta manual/images, i no en altres subcarpetes.

Anomenament

Per anomenar arxius utilitzar guionets baixos per separa capitols i seccions, i guionet mitg per separar seccions que es composen d’una o mes paraules. Per fixers d’imatges, hauria de ser: capitols_subseccio_sub-subseccio_id.png, com per exmple:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

No empreu caracters especials ni espais!

Guies D’ús

  • Cal evitar especificar la resolució de la imatge, de forma que el tema pugui gestionar les imatges de forma coherent i subministar la millor disposició en diferents tamanys de pantalla.

  • Quan es documenti un panell o una secció de la interfície da usuària, és millor utilitzar una imatge única que mostri totes les àrees rellevants (en lloc de múltiples imatges per a cada icona o botó) col·locades a la part superior de la secció que s’estigui escrivint i després explicar les característiques en l’ordre en què apareixen en l’imatge.

    Nota

    És important que el manual es pugui mantenir a llarg termini. Les opcions de la interfície d’usuària i de l’eina canvien, de manera que cal evitar incloure moltes imatges (quan no siguin especialment necessaries). En cas contrari, tot plegat genera massa feina de manteniment.

Vídeos

«Els vídeos es poden incrustar des de la instancia de PeerTube auto-allotjada del Blender que es pot trobar a video.blender.org. Per inserir un vídeoutilitzar la següent directiva:

.. peertube:: ID

El ID es troba en la URL del video, com per exemple:

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

Per carregar un nou vídeo, cal contactar el Administrador de documentació de projecte Project Administrator <https://projects.blender.org/blender/documentation>`__ o incloeu el video a la descripció d’un Pull Request.

Guies D’ús

  • Cal evitar videos basats en la veu o paraules, ja que en dificula la traducció.

  • No incrusteu tutorials de vídeo com a mitjà per explicar una funció, l’escriptura per si mateixa hauria d’explicar-ho adequadament. (Tot i que podeu incloure un enllaç al vídeo a la part inferior de la pàgina sota l’encapçalament Tutorials).

Construccions útils

  • |BLENDER_VERSION| – Es resol a la versió actual del Blender.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – Abreviatures Mostra el text complet com a pista per al lector.

  • :term:`Manifold` – Enllaços a una entrada del Glossari.

Referencies Creaudes i enllaços

Podeu enllaçar a un altre document al manual utilitzant:

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

Per enllaçar a una secció especifica en un altre document (o el mateix), es disposa d’etiquetes espcifíques:

.. _sample-label:

[section or image to reference]

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

Enllaç a un títol en el mateix document:

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

Body text.

Implicit references, like `Titles are Targets`_

Enllaç al món exterior:

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

Accés al Manual sensible al context

És possible enllaçar a una part específica del manual des del Blender obrint el menú contextual (clic dret) d’una propietat o operador i seleccionant Manual en línia. Perquè això funcioni, s’ha de tenir en compte a la documentació. Per enllaçar una propietat o un operador a una part específica del manual, heu d’afegir una etiqueta d’enllaç de referència externa l’identificador de la qual coincideix amb l’etiqueta RNA del Blender. La manera més senzilla d’esbrinar l’etiqueta és obrir el menú contextual de la propietat/operador i seleccionar Referencia Online de Python per extreure l’etiqueta de l’URL. A continuació es donen alguns exemples de com es veu això al document 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...

Per un operador:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Icones

Les icones de Blender es poden integrar dins un text emprant:

`:bl-icon:`<icon_name>`

Més informació

Per apender més sobre reStructuredText, vegeu:

Sphinx RST Primer

Bona introducció bàsica.

Docutils reStructuredText Reference

Enllaços a la documentació de referència i d’usuària.