Oblikovni vodič

Ta stran popisuje norme pri pisanju in uporabi oblikovne sintakse reStructuredTexta (RST).

Dogovori

  • Zamik s tremi presledki.

  • Vrstice naj bodo dolge manj kot 120 znakov.

  • Za imena gumbov/menijev uporabite poševno pisavo.

Ostali ohlapnejši dogovori:

  • Izogibajte se Unicode zapisom.

  • Izogibajte se neprenehnemu prehajanju v naslednjo vrstico (t. j. povedi imajo lahko svojo lastno vrstico).

Naslovje

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

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

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

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

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

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

Opomba

Part-i naj bodo uporabljeni le za kazalo ali naslovne strani (ang. index page).

Opomba

Vsaka datoteka .rst naj ima samo en naslov poglavja (*).

Oblika besedila

See the overview on ReStructuredText for more information on how to style the various elements of the documentation and on how to add lists, tables, pictures and code blocks. The Sphinx reference provides more insight additional constructs.

Spodaj so našteti še nekateri uporabni pribitki za oblikovanje besedila:

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

Elementi vmesnika

  • :kbd:`LMB` – bližnjice na tipkovnici in miški.

  • *Mirror* – oznake za vmesnik.

  • :menuselection:`3D Viewport --> Add --> Mesh --> Monkey` – menus.

Vzorci kode

Podprto je posebno označevanje sintakse, če navedete programski jezik, če želite, pa lahko prikažete tudi številke vrstic z možnostjo :linenos::

.. code-block:: python
   :linenos:

   import bpy
   def some_function():
       ...

Slike

Za postavljanje slik uporabite figure:

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

   Image caption.

Zavoljo doslednosti in ker je zaželeno, da so slike zaslona enakih velikosti, ko so prikazane poleg besedila, naj avtorji zajamejo zaslonske slike na naslednji način:

  1. Prepare the area you would like to capture making sure to use the default theme and setting. (In some cases you may not want to use the default settings e.g. if some options are hidden behind a checkbox.)

  2. Povečajte velikost na maksimum (držite NumpadPlus ali Ctrl-MMB ali podobno bližnjico).

  3. Pomanjšajte velikost za osem ravni (osemkrat pritisnite NumpadMinus).

  4. V nekaterih primerih boste hoteli pustiti majhen odmik okrog stvari, ki jo hočete zajeti. Naj bo odmik približno 30px, lahko malce več ali malo manj.

To velja za precej delov uporabniškega vmesnika, vendar ne za vse.

Datoteke

Brez velikih črk in presledkov

Imena datotek naj bodo z malimi črkami in s podčrtajem med besedami.

Sortirajte uporabno

Uredite imenovanje z določenimi oznakami na koncu.

Format

Uporabljajte .png za slike, ki imajo celostne barve, recimo slike Blenderjevega vmesnika, in .jpg za slike z večjimi razlikami v barvah, kot so primeri izrisov in fotografije.

Ne uporabljajte animiranih datotek .gif. Te je težko vzdrževati, lahko motijo bralca in velikokrat so večje v smislu velikosti datoteke. Če je že treba, uporabite videoposnetek (preberite si Videoposnetki spodaj).

Lokacija

Postavite sliko v mapo manual/images. Ne ustvarjajte podmap.

Imenovanje

Datoteke imenujte tako, da vključite poglavja in razdelke, ki jih ločite s podčrtaji, če pa je ime razdelka sestavljeno iz več besed, jih ločite s pomišljaji. Torej naj bi se slikovne datoteke imenovale poglavje_podrazdelek_pod-podrazdelek_id.png, npr:

  • interface_splash_current.png

  • interface_undo-redo_last.png

  • interface_undo-redo_repeat-history-menu.png

Ne uporabljajte posebnih znakov ali presledkov!

Vodiči za uporabo

  • Izogibajte se navajanju ločljivosti slike, da bodo vse slike obravnavane enako in bo na različnih zaslonih priročnik videti najbolje.

  • Ko dokumentirate ploščo ali razdelek uporabniškega vmesnika, je bolje, da dodate eno samo sliko, ki prikazuje vsa ustrezna področja (kot pa da dodate več slik, vsako za svojo ikono ali gumb), postavljeno na vrh razdelka, ki ga pišete, in nato razložite funkcije v vrstnem redu, v kakršnem se pojavljajo na sliki.

    Opomba

    Pomembno je, da priročnik vzdržujemo na dolgi rok. Uporabniški vmesnik in orodja se spreminjajo, zato se izogibajte dodajanju večje količine slik (kadar to ni potrebno). Drugače je to prevelik zalogaj za kakovostno vzdrževanje.

Videoposnetki

Videos can be embedded from Blender’s self-hosted PeerTube instance which can be found at video.blender.org. To embed a video using the following directive:

.. peertube:: ID

ID najdete v URL-ju posnetka, npr:

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

To get a new video uploaded, contact a Documentation Project Administrator or include the uploaded video in your Patch description.

Vodiči za uporabo

  • Avoid adding videos that rely on voice or words, as this is difficult to translate.

  • Do not embed video tutorials as a means of explaining a feature, the writing itself should explain it adequately. (Though you may include a link to the video at the bottom of the page under the heading Tutorials).

Uporabna navodila

  • |BLENDER_VERSION| – S tem označite trenutno različico Blenderja.

  • :abbr:`SSAO (Screen Space Ambient Occlusion)` – Okrajšave prikažejo polno besedilo, ko bralec podrži kurzor nad okrajšavo.

  • :term:`Manifold` – Se povezuje z vnosom v slovarčku.

Navajanje in povezave

Navedete lahko povezavo do drugega dokumenta v priročniku:

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

Za navajanje povezave do specifičnega razdelka v drugem (ali istem) dokumentu so na voljo eksplicitne oznake:

.. _sample-label:

[section or image to reference]

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

Povezava do naslova v isti datoteki:

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

Body text.

Implicit references, like `Titles are Targets`_

Povezava do zunanjega sveta:

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

Context Sensitive Manual Access

It is possible to link to a specific part of the manual from in Blender by opening the context menu (right click) of a property or operator and selecting Online Manual. In order for this to work, this needs to be accounted for in the documentation. To link a property or operator to a specific part of the manual you need to add an external reference link tag whose ID matches Blender’s RNA tag. The easiest way to find out what the tag for a property is to open the context menu of the property/operator and select Online Python Reference to extract the tag from the URL. Some examples of how this looks in the RST document are given below:

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

For an operator:

.. _bpy.ops.curve.subdivide:

Subdivide
=========

Nadaljujte z branjem

Za več informacij o reStructuredTextu si preberite:

Sphinx RST Primer

Dober osnovni uvod.

Docutils reStructuredText Reference

Povezava do sklicev in uporabniške dokumentacije.