Sprievodca štýlom značiek#

Táto stránka obsahuje konvencie pre písanie a použitie syntaxe značiek reStructuredText (RST).

Konvencie#

  • Odsadenie tri medzery.

  • Riadky by mali mať menej ako 120 znakov.

  • Pre názvy tlačidiel/ponúk používajte kurzívu.

Ostatné voľné konvencie:

  • Nepoužívajte znaky Unicode.

  • Nepoužívajte príliš zalomený text (t. j. vety majú mať svoje vlastné riadky).

Hlavičky#

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

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

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

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

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

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

Poznámka

Časti by sa mali používať iba pre obsah alebo indexové stránky.

Poznámka

Každý súbor .rst by mal mať iba jednu záhlavie kapitoly (*) na súbor.

Štýl textu#

Pre viac informácií ako upravovať rôzne prvky dokumentácie a ako pridávať zoznamy, tabuľky, obrázky a bloky kódov si pozrite na prehľad ReStructuredText. Stránka Sphinx poskytuje podrobnejší prehľad ďalších konštrukcií.

Nasledujúce užitočné značky pre štylizáciu textu:

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

Prvky rozhrania#

  • :kbd:`ĽTM` – skratky klávesnicou a myšou.

  • *Zrkadlo* – návesti rozhrania.

  • :menuselection:`3D záber --> Pridať --> Povrchová sieť --> Opička` – ponuky.

Ukážky kódu#

Ak je k dispozícii programovací jazyk, existuje podpora pre zvýraznenie syntaxe a čísla riadkov je možné voliteľne zobraziť použitím možnosti :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Obrázky#

Na umiestnenie obrázkov by sa mali použiť figúry:

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

   Image caption.

Kvôli príslušnosti a pretože by bolo dobré zaistiť, aby všetky snímky obrazovky mali podobnú veľkosť, keď sú umiestnené vedľa textu, mali by autori snímok obrazovky robiť nasledujúcim spôsobom:

  1. Pripravte si oblasť, ktorú chcete zachytiť, aby ste použili predvolenú tému a nastavenie. (V niektorých prípadoch možno nebudete môcť použiť predvolené nastavenia, napr. ak sú niektoré možnosti skryté za zaškrtávacím políčkom.)

  2. Priblížiť na maximálnu úroveň priblíženia (podržte NumPlus alebo Ctrl+STM alebo podobné).

  3. Oddialenie ôsmich úrovní priblíženia (NumMínus – osemkrát).

  4. V niektorých prípadoch budete chcieť nechať okolo objektu, ktorý sa snažíte zachytiť, malú rezervu. Mal by byť okolo 30 pixelov, ale nemusí to byť presné.

Toto možno použiť na niekoľko častí rozhrania, ale nemusí to fungovať vo všetkých prípadoch.

Súbory#

Žiadne kapitálky, žiadne medzery

Názvy súborov malými písmenami, podčiarkovník medzi slovami.

Vhodne usporiadať

Pomenovať príkaz s určenými identifikátormi na konci.

Formát

Používajte formát .png pre obrázky, ktoré majú plné farby tak ako snímky obrazovky rozhrania Blenderu a .jpg pre obrázky s veľkou variabilitou farieb, ako sú napríklad snímky vytvoreného prekreslenia a fotografie.

Nepoužívajte animované súbory .gif, ktoré sa ťažko udržiavajú, môžu pôsobiť rušivo a zvyčajne majú príliš veľký súbor. Namiesto toho podľa potreby použite video (pozri videá nižšie).

Poloha

Vložte obrázok do priečinka manual/images. Nepoužívajte žiadne ďalšie podpriečinky.

Pomenovanie

Pri pomenovávaní súborov používajte podčiarkovníky na oddelenie kapitol a častí a pomlčky na oddelenie častí, ktoré tvoria dve alebo viac slov. Takže obrazové súbory by mali vyzerať takto: kapitola_subsection_sub-subsection_id.png, napr.:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

Nepoužívajte špeciálne znaky ani medzery!

Sprievodcovia používaním#

  • Neudávajte rozlíšenie obrázka, aby téma mohla s obrázkami narábať konzistentne a poskytovala najlepšie rozloženie v rôznych veľkostiach obrazovky.

  • Pri dokumentovaní panela alebo časti užívateľského rozhrania je lepšie použiť jeden obrázok, ktorý zobrazuje všetky príslušné oblasti (namiesto viacerých obrázkov pre každú ikonu alebo tlačidlo) umiestnené v hornej časti, ktorú píšete a potom vysvetliť poradie, v akom sa nachádzajú na obrázku.

    Poznámka

    Je to dôležité, kvôli dlhodobej údržbe manuálu, zmene užívateľského rozhrania a možnosti nástrojov, takže sa snažte vyhnúť tomu, aby ste mali veľa obrázkov (ak to nie je zvlášť potrebné). V opačnom prípade to znamená príliš veľkú záťaž pre údržbu.

Videá#

Videá je možné vkladať z inštancie PeerTube, ktorá sa nachádza na adrese video.blender.org. Ak chcete vložiť video pomocou nasledujúcej usmernenia:

.. peertube:: ID

ID sa nachádza v adrese URL videa, napríklad:

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

Ak chcete nahrať nové video, kontaktujte správcu projektu Projekt dokumentácie alebo uveďte nahrané video v popise Natiahnuť požiadavku.

Sprievodcovia používaním#

  • Vyhnite sa pridávaniu videí, ktoré sa spoliehajú na hlas a slová, pretože je ťažké ich preložiť.

  • Nevkladajte video návody ako prostriedok na vysvetlenie funkcie, samotný text by ju mal dostatočne vysvetliť. (Hoci môžete uviesť odkaz na video v dolnej časti stránky pod nadpisom Tutoriály).

Užitočné konštrukcie#

  • |BLENDER_VERSION| – Uvedie aktuálnu verziu Blenderu.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – Skratky zobrazujú celý text ako popis pre čitateľa.

  • :term:`Nevyvinuté <Manifold>` – Odkazy na záznam v Slovníku.

Krížové odkazy a väzby#

V manuáli môžete vytvoriť odkaz na iný dokument použitím:

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

Ak chcete vytvoriť odkaz na konkrétnu sekciu v inom dokumente (alebo v tom istom), sú k dispozícii jednoznačné návestia:

.. _sample-label:

[section or image to reference]

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

Odkaz na titulok v rovnakom súbore:

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

Body text.

Implicit references, like `Titles are Targets`_

Prepojenie s vonkajším svetom:

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

Prístup citlivých kontextov manuálu#

Na konkrétnu časť manuálu je možné odkázať v programe Blender otvorením kontextovej ponuky (kliknutím pravým tlačidlom myši) vlastnosti alebo operátora a výberom položky Online manuál. Aby to fungovalo, je potrebné s tým počítať v dokumentácii. Ak chcete prepojiť vlastnosť alebo operátor s konkrétnou časťou príručky, musíte pridať značku odkazu na externý odkaz, ktorej ID sa zhoduje so značkou RNA programu Blender. Najjednoduchší spôsob, ako zistiť, aký je príznak pre vlastnosť, je otvoriť kontextovú ponuku vlastnosti/operátora a vybrať položku Online Python Reference, aby ste získali príznak z adresy URL. Niektoré príklady, ako to vyzerá v dokumente RST, sú uvedené nižšie:

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

Pre operátor:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Ďalšie čítanie#

Ak sa chcete dozvedieť viac informácií o reStructuredText, pozrite si:

Základy Sphinx RST

Dobrý úvodný základ.

Referenčná príručka reStructuredText

Odkazy na referenčnú a užívateľskú dokumentáciu.