Stilguide för uppmärkning¶

På den här sidan beskrivs konventioner för att skriva Blenders dokumentation med hjälp av reStructuredText (RST) markup-syntax. Genom att följa dessa konventioner säkerställs tydlighet, konsekvens och enkelt underhåll.

Allmänna konventioner¶

Använd ett indrag med tre mellanrum.
Begränsa radlängden till 120 tecken.
Använd kursiv stil för knapp- och menynamn.
Undvik att använda Unicode-tecken om det inte är absolut nödvändigt.
Föredrar enkla meningsbyggnader för tydlighetens skull.
Undvik mycket text (kortare stycken och tydliga meningar är att rekommendera).

Rubriker¶

Använd följande hierarki för rubriker:

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

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

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

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

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

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

Observera

Varje .rst-fil bör endast ha en kapitelrubrik (*).
Parts bör endast användas på innehålls- eller indexsidor.

Grundläggande textstyling¶

Vanliga textstilar som används i hela dokumentationen:

*italic text*
**bold text**
``literal text`` (e.g., filenames, Python code snippets)

Gränssnittselement¶

Standardmarkup för gränssnittselement:

:kbd:`VMK` – kortkommandon för tangentbord och mus.
*Mirror* – gränssnittsetiketter (knappar, paneler etc.).
:menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – navigationsvägar genom menyer.

Listor¶

Listor används för att tydligt presentera sekventiella eller grupperade objekt:

Punktlista

- First item
- Second item
- Third item

Numrerad lista:

#. First step
#. Second step
#. Third step

Definition Lista:

Term
   Definition text here.

Användbara konstruktioner¶

|BLENDER_VERSION|: Infogar den aktuella Blender-versionen automatiskt.
:abbr:`SSAO (Screen Space Ambient Occlusion)`: Förkortningen visar hela texten vid hovring.
:term:`Manifold`: Länkar till motsvarande post i Ordlista.
:bl-icon:`icon_name`: Inkludera Blender-ikoner som inline-text, se den fullständiga listan på Ikoner.

Korsreferenser och länkar¶

Länkar till interna dokument:

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

Länka till ett specifikt avsnitt med hjälp av tydliga etiketter:

.. _my-section-label:

Section Title
=============

Reference this section later with :ref:`Optional Title <my-section-label>`

Implicita referenser inom samma dokument:

Section Title
=============

Reference it implicitly later using `Section Title`_

Externa länkar till webbplatsen:

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

Kontextkänslig manuell åtkomst¶

För att länka Blender UI egenskaper och operatörer direkt till manuella poster:

Högerklicka på egenskapen/operatorn i Blender och välj Online Python Reference för att få fram RNA-taggen (visas i OS-konsolen).
I dokumentationen ska du använda en extern referens som matchar Blenders RNA-tagg:

.. _bpy.types.FluidDomainSettings.use_fractions:

Fractional Obstacles
   Enables finer resolution in fluid/obstacle regions.

För operatörer:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Blender använder dessa taggar för att länka UI-element direkt till dokumentationsposter via alternativet ”Online Manual”.

Förmaningar¶

Admonitions är speciella block som används för att markera viktiga anmärkningar, varningar eller ytterligare information i dokumentationen.

Vanliga typer av uppmaningar inkluderar:

note
tip
important
warning
caution
seealso

Förmaningar skapas med hjälp av följande markering:

.. note::

   This is a note for general information.

Andra typer kan återges genom att ersätta note med önskad typ från listan ovan.

Bilder¶

Använd figure-direktivet för att bädda in bilder med bildtexter:

.. figure:: /images/interface_splash_current.png

   Splash screen of Blender.

Riktlinjer för skärmdumpar¶

För att säkerställa enhetlighet mellan skärmdumpar:

Använd Blenders standardtema och standardinställningar.
Zooma till maximal nivå (Ctrl-MMB eller NumpadPlus).
Zooma ut exakt åtta steg (NumpadMinus, tryck åtta gånger).
Lämna en marginal på cirka 30 pixlar runt innehållet, om tillämpligt.

Namngivning av filer¶

Följ dessa riktlinjer för namngivning av bildfiler:

Använd små bokstäver, inga mellanslag, understrykningstecken mellan avsnitt och bindestreck i avsnitt med flera ord.
Placera bilderna endast i katalogen manual/images (inga undermappar).

Exempel:

gränssnitt_splash_current.png
Modellering_meshes_edit-mode.png

Bildformat¶

.png: För skärmdumpar av gränssnitt eller bilder i fast färg.
.jpg: För fotografiska bilder eller renderingar med hög färgvariation.
Undvik .gif; använd istället inbäddade videor för animationer.

Videor¶

Bädda in videor som finns på Blender’s PeerTube på video.blender.org.

.. peertube:: ID

”ID” extraheras från videons URL, t.ex.:

https://video.blender.org/videos/watch/47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c ID:t är: 47448bc1-0cc0-4bd1-b6c8-9115d8f7e08c.

Riktlinjer för videor¶

Föredrar videor utan talade eller textuella förklaringar för enklare översättning.
Förlita dig inte enbart på videor för att förklara funktioner. Själva manualtexten bör tydligt dokumentera processen.

Kodprover¶

Kodsnuttar bör använda syntaxmarkering och valfri radnumrering:

.. code-block:: python
   :linenos:

   import bpy

   def example_function():
       print("Hello Blender")

Platshållare och redaktörsanteckningar¶

För innehåll som behöver uppdateras eller kompletteras i framtiden:

Synlig för läsarna:

.. todo:: Complete this section when feature is finalized.

Interna anteckningar (ej synliga för läsare):

.. Internal developer reminder goes here

Ytterligare läsning¶

Sphinx RST-grundkurs: Introduktion till RST-syntax.
Docutils reStructuredText-referens: Omfattande dokumentation om RST-markup.