2. Директиве¶

2.1.1. Директива image¶

Облик директива image дат је у следећем примеру:

.. image:: slika.jpeg
    :height: 100px
    :width: 200 px
    :scale: 50 %
    :alt: алтернативни текст
    :align: right

Уместо slika.jpeg треба навести име фајла са сликом коју желимо да додамо. Име фајла може да се наведе са релативном или апсолутном путањом. Петљини документи по правилу садрже само релативне путање до слика.

Уз директиву image Сфинкс препознаје опције :alt:, :align:, :height:, :width: и :scale:.

Опцијом :alt: се задаје текст, који ће се појавити као алтернатива слици у случају да слика из било ког разлога не буде приказана. Неке апликације, које су у стању да изговарају текст документа, користе овај текст и изговарају га уместо слике.

Од опција :height:, :width: и :scale:, најчешће се користи само једна. Ако се користе две или све три ове опције, њихово дејство се комбинује.

Опција :height: задаје жељену висину текста. После назива опције наводи се бројчана вредност у пикселима (ознака px иза броја може да се наведе, а ако се не наведе, подразумева се). На пример, кôд

.. image:: ../../_images/emotikon.png
    :height: 50

даје

Слично овоме, опција :width: задаје жељену ширину текста. Вредност која се наводи може да буде у пикселима (px) или у процентима (%) ширине блока који садржи слику. Ако се не наведе јединица, подразумева се px, тј. подразумева се да је дата ширина у пикселима. Тако, кôд

.. image:: ../../_images/emotikon.png
    :width: 75 px

даје

Ако се користи и опција :width: и опција :height:, обе ће бити примењене, што може да деформише слику. На пример, кôд

.. image:: ../../_images/emotikon.png
    :height: 50
    :width: 200

даје

Опција :scale: задаје коефицијент умањења или увећања оригиналне величние слике. Овај коефицијент је цео број у процентима и ознака % се подразумева (ако се не наведе). Вредност 100 значи оригиналну величину, 200 значи двоструко већу слику, 50 значи двоструко мању слику, итд.

Ако се опција :scale: користи заједно са било којом од опција :width: и :height: (или обема), њихово дејство се комбинује. На пример, ако се зада :width: 300 px и :scale: 50%, то је исто као да је задата опција :width: 150 px без опције :scale:.

Опција :align: се користи да се зада поравнање слике се ивицама блока који је садржи. Могуће вредности су top, middle, bottom, left, center, или right. Вредности top, middle и bottom одређују вертикално поравнање у односу на оновну линију текста (text bseline). Ове вредности имају смисла једино код супституција (види Супституције). Вредности left, center и right задају хоризонтално поравнање. Вредност center се користи да центрира слику по хоризонтали и онемогући појављивање текста и осталог садржаја лево и десно од слике. Вредности left и right постављају слику уз леву, односно десну ивицу блока и дозвољавају да се текст и остали садржај појави поред слике. Овај начин приказивања се у Петљиним документима понекад не комбинује добро са сложенијим садржајем наведеним после слике (конкретно понашање зависи и од веб прегледача), па се препоручује да се користи само када после слике следи довољно текста.

Опција :target: се користи када је слика уједно и хипервеза. Вредност ове опције задаје одредиште хипервезе. Кликом на слику, веб прегледач нас пребацује на наведено одредиште. На пример, следећи кôд у RST фајлу даје слику-хипервезу, чије је одредиште почетак овог одељка (кликните и испробајте).

.. image:: ../../_images/emotikon.png
    :height: 50
    :target: `Директива image`_

Резултат:

2.1.2. Директива figure¶

Директива figure се понаша као директива image, уз додатак да испод слике може да се допише коментар (опис или објашњење слике, одакле је преузета и сл.). Коментар испод слике се пише након једног празног реда, поравнат са опцијама директиве, а може да се простире и на више параграфа. Следи пример reST кода и резултата у HTML документу:

.. figure:: ../../_images/emotikon.png
    :height: 100px
    :alt: насмејано лице
    :align: center

    Слика насмејаног лица

    која постоји и као *Unicode* карактер

Слика насмејаног лица¶

која постоји и као Unicode карактер

За слике задате помоћу директиве figure није могуће дефинисати замену (супституцију).

2.1.3. Галерија слика¶

Петљадок нам омогућава да у пројекте ставимо и галерију слика која нам омогућује да листамо изабране слике. Галерију у пројекат додајемо помоћу директиве gallery. Изворни код за ову директиву изгледа овако

.. gallery:: primer_galerija
    :folder: ../../_images
    :images: galerija_slika1.png, galerija_slika2.jpg, galerija_slika3.png, galerija_slika4.jpg
    :width:
    :height:

И овако употребљена галерија даје ово у браузеру:

Приметимо да је потребно дефинисати (релативну) путању до фолдера у коме се налазе слике, у приказаном случају то је фолдер _images у root-у пројекта. Након тога у опцији images наводе се називи слика које ће бити укључене у галерију. Називи се наводе без путање, са екстензијама, раздвојене зарезима (а пожељан је и размак после зареза).

Важно је обратити пажњу и на вредности width и height. Ако оне нису наведене, максимална ширина и висина слика биће 780рх. Ако су слике мање од 780x780px биће приказане у својим оригиналним димензијама. Ако је ширина слике већа од 780рх, ширина ће бити смањена на 780, а висина ће бити скалирана тако да се однос страница буде исти као код оригиналне слике (слика неће изгледати деформисано).

Ако су димензије ширине и висине галерије наведене, све слике у галерији биће сведене на те димензије (може доћи до деформација слика). Видећемо сада исту галерију којој су дефинисане димензије 300х300рх.

.. gallery:: primer_galerija
    :folder: ../../_images
    :images: galerija_slika1.png, galerija_slika2.jpg, galerija_slika3.png, galerija_slika4.jpg
    :width: 300px
    :height: 300px

И овако употребљена галерија даје ово у браузеру:

На крају, у истој галерији могу бити слике и формата .jpg и .png.

2.2.1. Замена за слику¶

Дефиниција замене пише се једном у сваком фајлу у коме се користи. Она се обично налази на почетку фајла, а може да се напише било где у фајлу, па чак и после места употребе. Дефиниција замене иегледа овако:

.. |дугме тест| image:: ../../_images/test.png
                :height: 18 px

Овом дефиницијом је уведена ознака |дугме тест| и она ће представљати (бити замена за) слику test.png.

Ако се висина наведе, она мора да буде поравната као у примеру. Ако се не наведе, користи се оригинална висина слике. Осим висине, могу да се наведу и све друге опције, са вредностима које у овом контексту имају смисла. Конкретније, уз опцију :align: овде имају смисла само вредности top, middle и bottom, јер оне вертикално поравнавају слику са текстом.

На месту употребе, ознака |дугме тест| треба да се уметне на оно место у тексту, на коме желимо да се појави слика. Следи пример.

reST

Притиском на |дугме тест| покреће се детаљније тестирање.
Ако тестирање траје дуже, током тестирања не треба поново притискати |дугме тест|.

Изглед у веб прегледачу:

Притиском на покреће се детаљније тестирање. Ако тестирање траје дуже, током тестирања не треба поново притискати .

2.2.2. Замена за текст¶

Замена за текст се обично користи када нам се у тексту више пута појављује нека фраза или компликованији текст (могуће заједно са ознакама за форматирање), чије понављање желимо да избегнемо.

.. |VS| replace:: *Visual Studio*

|VS| је веома богато окружење за развој софтвера. Окружење |VS| се јавља
у више издања, од којих је издање *Community* бесплатно за употребу.
|VS| нам нуди и напредне могућности, попут профилирања програма, успостављања
везе са софтвером за контролу верзија, креирање инсталационих пакета итд.

.. |AB| replace:: :math:`\overrightarrow{\rm AB}`
.. |DC| replace:: :math:`\overrightarrow{\rm DC}`

У паралелограму :math:`ABCD` су вектори |AB| и |DC| једнаки, па транслацијом тачке
:math:`D` за вектор |AB| добијамо тачку :math:`C`. Тачке :math:`M` и :math:`N` сада
можемо да добијемо транслирањем тачака :math:`B` и :math:`C` за вектор |AB| редом,
након чега се задатак лако решава.

2.4.1. Садржај у оквиру документа -toctree¶

Директиву toctree користимо како бисмо (било где у нашем пројекту) направили садржај, који упућује на друге делове нашег пројекта. Директиву користимо тако што у телу директиве наводимо листу ралативних путања од фајла у коме се налази садржај ка осталим фајловима које желимо да укључимо у наш садржај.

Када у садржају наводите путање ка фајловима, да бисте навели правилне релативне путање до изворних фајлова, увек узмите у обзир стрктуру свог _sources фолдера. Структура нашег _sources фолдера изледа као на шеми испод, па су и путање у директиви у фајлу 00_rst_petljadoc_intro/01_intro.rst усклађене са тиме.

_sources
    ├───00_rst_petljadoc_intro
    │   └───01_intro.rst
    ├───01_quick_start
    │   └───01_quick_start.rst
    ├───02_basics
    │   ├───01_formatting.rst
    │   ├───02_directives.rst
    │   ├───03_formating_directives_quiz.rst
    │   ├───04_questions.rst
    │   └───05_quiz_example.rst
    ├───03_active_code
    │   ├───01_active_code.rst
    │   ├───02_other_languages.rst
    │   ├───03_simanim.rst
    │   ├───04_p5js.rst
    │   └───05_karel.rst
    └───index.yaml

Следећи кôд представља пример употребе директиве toctree.

.. toctree::
    :maxdepth: 2
    :caption: Садржај
    :numbered:

    ../01_quick_start/01_quick_start.rst
    ../02_basics/01_formatting.rst
    ../02_basics/02_directives.rst
    ../02_basics/03_formating_directives_quiz.rst
    ../02_basics/04_questions.rst
    ../02_basics/05_quiz_example.rst
    ../03_active_code/01_active_code.rst
    ../03_active_code/02_other_languages.rst
    ../03_active_code/03_simanim.rst
    ../03_active_code/04_p5js.rst
    ../03_active_code/05_karel.rst

Изглед садржаја можете да видите на дну почетне стране. Овде не можемо да поновимо приказ комплетног садржаја, јер бисмо таквом употребом директиве toctree направили кружне референце у садржају, па овај документ не би могао да буде формиран.

Наиме, ако неки од фајлова набројаних у телу директиве toctree садржи другу директиву toctree, садржај који та друга директива формира се уврштава у садржај који правимо првом директивом. Овај поступак тече рекурзивно, тако да се од расутих, хијерархијски организованих садржаја поједних делова (поглавља) једноставно формира свеоубухватан, главни садржај.

Опција maxdepth коју смо употребили, контролише који ће ниво наслова бити укључен у наш садржај. Њој као аргумент прослеђујемо цео број, који треба да представља ред наслова који ћемо укључити у садржај. Ако бисмо искористили број 3, у садржај би били укључени наслови првог, другог и трећег реда (погледајте садржај на почетку овог поглавља). Ако не употребимо ову опцију, у садржај ће бити укључени сви наслови.

Директива toctree има још и опције numbered, која нема аргументе и служи да нумерише све наслове и поднаслове нашег садржаја, и caption која као аргумент узима стринг који ће служити као наслов нашег садржаја.

2.4.2. Садржај у оквиру лекције - contents¶

Садржај се може направити и помоћу директиве contents. За разлику од директиве toctree, ова директива не прихвата ништа у телу директиве и служи да се, најчешће на почетку лекције, понуди садржај за ту лекцију. Као аргумент при позиву директиве ставља се стринг који ће представљати наслов садржаја, а помоћу опције depth одређује се који ће ниво хијерархије поднаслова бити укључен у садржај. Испод је пример коришћења ове директиве са дубином 2, а на почетку овог поглавља можете видети како изгледа када се директива употреби са дубином 3.

.. contents:: Наслов садржаја
    :depth: 2

2.5.1. Директива infonote¶

reST кôд:

.. infonote:: Директива infonote

    Овако изгледа директива ``infonote``. У њу стављамо напомену, резиме лекције или сличан текст од посебног значаја за полазнике курсева.

Овако изгледа директива infonote. У њу стављамо напомену, резиме лекције или сличан текст од посебног значаја за полазнике курсева.

2.5.2. Директива questionnote¶

reST кôд:

.. questionnote::

    Овако изгледа директива ``questionnote``.
    Обично садржи текст питања, уз који могу да се користе слике, делови програмског кода и слично.

2.5.3. Директива learnmorenote¶

reST кôд:

.. learnmorenote::

    Овако изгледа директива ``learnmorenote``. У њу стављамо разне врсте савета, као што су:

    - пружање додатне помоћи пре извршења неког задатка,
    - навођење полазника на алтернативне приступе размишљања о задатку.

Овако изгледа директива learnmorenote. У њу стављамо разне врсте савета, као што су:

• пружање додатне помоћи пре извршења неког задатка,

• навођење полазника на алтернативне приступе размишљања о задатку.

2.5.4. Директива suggestionnote¶

reST кôд:

.. suggestionnote::

    Овако изгледа директива ``suggestionnote``. Уобичајени поднаслов у овим оквирима је "За оне који желе да знају више".
    Овако истичемо додатне информације које нису предвиђене програмом, нпр. занимљиве чињенице, или усмерења ка даљој литератури и ресурсима за учење.

Овако изгледа директива suggestionnote. Уобичајени поднаслов у овим оквирима је „За оне који желе да знају више”. Овако истичемо додатне информације које нису предвиђене програмом, нпр. занимљиве чињенице, или усмерења ка даљој литератури и ресурсима за учење.

2.5.5. Директива technicalnote¶

reST кôд:

.. technicalnote::

    Овако изгледа директива ``technicalnote``.
    Служи као упутство за решавање различитих техничких питања као што су инсталирање и покретање програма, системска подешавања и др.

Овако изгледа директива technicalnote. Служи као упутство за решавање различитих техничких питања као што су инсталирање и покретање програма, системска подешавања и др.

2.5.6. Директива topic¶

reST кôд:

.. topic:: Неки појам или заглавље

    Овако изгледа директива ``topic``.
    Обично садржи дефиницију појма, или други важан текст.

Ако желимо само да истакнемо текст, а да при томе не користимо истакнуту реч у врху (заглавље), иза директиве .. topic:: и размака можемо да наведемо \, што представља „празну реч”.

reST кôд:

.. topic:: \

    Важан текст.

2.5.7. Директива reveal¶

Директиву reveal користимо када желимо да неки елемент буде доступан само ако се кликне на одређено дугме. У општем облику ова директива изгледа овако:

.. reveal:: jedinstveni_id
    :showtitle: О теми xy
    :hidetitle: Сакриј текст о теми xy

    **О теми xy**

    Овде пишемо део документа који желимо да буде приказан само када се кликне на дугме.
    То може да буде текст или друге (додатно увучене) директиве.

Горњи код ће се у браузеру приказати овако:

Уместо jedinstveni_id потребно је сваки пут када се користи директива ставити неки јединствени стринг. Вредности атрибута :showtitle: и :hidetitle: представљају текст који ће се приказати на дугмету за показивање/скривање елемента.

Oва директива може бити посебно корисна када желимо да одређени елемент учинимо опционим за сам материјал који пишемо. На пример, када желимо да ставимо напомену, занимљивост или неки сличан додатни садржај.

Када у оквиру ове директиве користимо неку другу директиву, важно је да пазимо на увлачење. Овај случај можемо видети на следећем примеру:

.. reveal:: sazna_vise
    :showtitle: Сазнај више
    :hidetitle: Сакриј прозор

    Обичан текст.

    .. infonote::

        Овде видимо како је директива infonote смештена у оквиру дирекиве reveal.
        Форматирање параграфа са специјалним истицањем видеће се само после клика на дугме

    Још обичног текста.

У документу, то изгледа овако:

Обичан текст.

Овде видимо како је директива infonote смештена у оквиру дирекиве reveal. Форматирање параграфа са специјалним истицањем видеће се само после клика на дугме

Још обичног текста.

2.6.1. Табеле цртањем решетке¶

Табела може да се зада цртањем ивица њених ћелија.

• Знацима ==== се раздваја ред заглавља од осталих редова;

• Знацима ---- се раздвајају остали редови табеле међусобно и уоквирује се табела са горње и доње стране;

• Kолоне се раздвајају знаком |;

• У пресецима усправних и водоравних линија се пише знак``+``.

Пример

reST

+--------------------+---------------------------+---------------------------------------+
| Заглавље колоне 1  | Заглавље колоне 2         | Заглавље колоне 3                     |
+====================+===========================+=======================================+
| Тело Ред 1 Кол 1   | Тело Ред 1 Кол 2          | Тело Ред 1 Кол 3                      |
+--------------------+---------------------------+---------------------------------------+
| Тело Ред 2 Кол 1   | Ћелије могу да се  простиру на више колона.                       |
+--------------------+---------------------------+---------------------------------------+
| Тело Ред 3 Кол 1   | Ћелије могу да се         | - листа                               |
+--------------------+ простиру на више редова.  | - у ћелији                            |
| Тело Ред 4 Кол 1   |                           | - табеле.                             |
+--------------------+---------------------------+---------------------------------------+

Изглед у документу:

Постоји и једноставнији начин да се формира табела цртањем решетке, али овај начин нема све могућности као претходни: ћелије не могу да се простиру на више редова или колона и не могу да садрже више редова текста.

Пример:

reST

====================  =======================   ==========================
Заглавље 1            Заглавље 2                Заглавље 3
====================  =======================   ==========================
Тело Ред 1 Кол 1      Тело Ред 1 Кол 2          Тело Ред 1 Кол 3
Тело Ред 2 Кол 1      Тело Ред 2 Кол 2          Тело Ред 2 Кол 3
Тело Ред 3 Кол 1      Тело Ред 3 Кол 2          Тело Ред 3 Кол 3
Тело Ред 4 Кол 1      Тело Ред 4 Кол 2          Тело Ред 4 Кол 3
====================  =======================   ==========================

Изглед у документу:

Цела решетка, било на који начин да је цртана, може и да се смести у директиву table, испод које онда могу да се наведу опције за дефинисање поравнања и ширине колона. Наведене ширине задају однос у коме желимо да се укупна расположива ширина на екрану подели на поједине колоне. На пример:

reST

.. table::
    :align: left
    :widths: 10, 20, 20, 20

    ======================   ==============  ==============   ==============
     Ред \\ Колона            Колона ``A``    Колона ``B``     Колона ``C``
    ======================   ==============  ==============   ==============
     **Ред 1**                Поље ``A1``     Поље ``B1``      Поље ``C1``
     **Ред 2**                Поље ``A2``     Поље ``B2``      Поље ``C2``
     **Ред 3**                Поље ``A3``     Поље ``B3``      Поље ``C3``
     **Ред 4**                Поље ``A4``     Поље ``B4``      Поље ``C4``
    ======================   ==============  ==============   ==============

даје

2.6.2. Табеле у CSV формату¶

Табела може да буде задата и помоћу директиве csv-table. Формат је у суштини исти као у CSV фајловима, па се садржај оваквих фајлова по потреби лако убацује у документ. У наставку иза имена директиве се пише коментар или опис, који ће бити приказан испод табеле.

• Опцијом :header: се задају заглавља колона. Вредности за поједине колоне треба навести раздвојене зарезима.

• Опцијом :widths: се задају релативне ширине колона. Вредности за поједине колоне треба навести раздвојене зарезима. Ширина блока који садржи табелу ће у том односу бити подељена на колоне.

• Опцијом :align: се задаје поравнање у свакој ћелији табеле.

Сваки ред блока текста у наставку треба да има онолико делова колико табела има колона. Делови треба да буду раздвојени зарезима. Текст ћелије који садржи зарезе треба писати под наводницима. На тај начин се ти зарези не сматрају раздвајачима колона.

Када је потребно да се у пољу табеле појаве наводници, те наводнике треба писати после обрнуте косе црте, овако \".

Пример

reST

.. csv-table:: синтакса
    :header: Појам, опис, пример
    :widths: 10, 40, 50
    :align: left

    Цео број,  "низ цифара, испред кога може да буде плус или минус",  -123
    стринг, "низ било којих симбола који почиње једеноструким или двоструким наводником, а завршава се истим таквим наводником",  \"текст\"
    Идентификатор, "низ слова, подвлака и цифара, који не почиње цифром",  gornji_levi_deo

Изглед у документу:

2.10.1. Пример тежине нивоа 1¶

Са леве стране овог одељка лекције видећете зелену линију. Ако погледате код, видећете да смо употребили директиву level изнад питања.

.. level:: 1

.. infonote:: Задатак 1.

    Опишите како би требало да реагује лифт, ако у њега уђе више људи него што је предвиђено.

Задатак 1.

Опишите како би требало да реагује лифт, ако у њега уђе више људи него што је предвиђено.

2.10.2. Пример тежине нивоа 2¶

Са леве стране овог одељка лекције видећете жуту линију. Ако погледате код, видећете да смо употребили директиву level само изнад параграфа који сада читате.

Пример тежине нивоа 2
'''''''''''''''''''''

.. level:: 2

Са леве стране овог одељка лекције видећете жуту линију. Ако погледате код,
видећете да смо употребили директиву ``level`` само изнад параграфа који сада читате.

2.10.3. Пример тежине нивоа 3¶

Са леве стране овог одељка лекције видећете црвену линију. Ако погелдате код, видећете да смо употребили директиву level само изнад слике.

.. level:: 3

.. image:: ../../_images/emotikon.png
    :height: 50

2.10.4. Пример хијерархије и обележавања¶

У одељак текста који сада читате додали смо још један поднаслов који ће нам послужити да покаже како директива level функциониише. Видећете да су параграф који сада читате и поднаслов који се налази изнад њега остали необележени пошто је директива употребљена у оквиру поднаслова са нижим нивоом хијерархије.

Показни параграф
................

.. level:: 3

У оквиру овог поднаслова упторебили смо директиву ``level``.
Са леве стране се види да су обележени само овај текст и први поднаслов изнад њега.