ЯЗЫК РАЗМЕТКИ ДАННЫХ

reStructuredText
reStructuredText — язык разметки открытого текста по умолчанию, используемый Sphinx. Рассмотрим краткое введение в концепции и синтаксис языка.

Основная цель reStructuredText — определить и реализовать синтаксис разметки для использования в строках документации Python и других доменах документации, который будет удобочитаемым и простым, но достаточно мощным для нетривиального использования.




Целью разметки является преобразование документов reStructuredText в полезные форматы структурированных данных.
Пример страницы на reStructuredText
Сверхяркий светодиод
-----------------------


:download:`Скачать файл с классов <LED_3W_Module.py>`

**Светодиод** - это полупроводниковый прибор.
Когда через полупроводники проходит электрический ток, отрицательный заряд электронов соединяются с ионами
положительно заряженных дырок. В этот момент выделяется энергия, и мы видим излучение света.

.. image:: 3W_LED_Module.png
    :width: 100px
    :align: center

Класс
*****

.. py:class::
    LED_3W_Module
    
Класс используется для определения объектов, имеющих поведение светодиода 
    
Пример объявления объекта::

    led=LED_3W_Module(pin1)

.. py:function:: led.on()

    Команда позволяет включить светодиод

.. py:function:: led.off()

    Команда позволяет выключить светодиод

.. py:function:: led.bright(arg:int)

    Команда включает светодиод с указанной яркостью (0-1023)

Пример программы
****************

.. include:: sample.py
    :code: python
Документация языка
Markdown
Markdown — облегчённый язык разметки, созданный с целью обозначения форматирования в простом тексте, с максимальным сохранением его читаемости человеком, и пригодный для машинного преобразования в языки для различные публикации

Главный пример использования Markdown, с которым мы часто сталкиваемся — файлы readme.md, которые есть в каждом репозитории на Гитхабе. md в имени файла это как раз сокращение от markdown.



Другой частый пример — сообщения в мессенджерах. Можно поставить звёздочки вокруг текста в Телеграме, и текст станет полужирным.


Очень удобно работать с разметкой Markdown через программу Obsidian
Пример страницы на Markdown
### Заголовки

# Это заголовок 1
## Это заголовок 2
### Это заголовок 3
#### Это заголовок 4
##### Это заголовок 5
###### Это заголовок 6


### Выделение

*Этот текст будет выделен курсивом*
_Этот текст тоже будет выделен курсивом_

**Этот текст будет выделен жирным шрифтом**
__Этот текст тоже будет выделен жирным шрифтом__

_Их **можно** комбинировать_


### Списки

- Предмет 1
- Предмет 2
  - Предмет 2a
  - Предмет 2b

1. Предмет 1
1. Предмет 2
1. Предмет 3
   1. Предмет 3a
   1. Предмет 3b


### Изображения

![Энгельбарт](https://history-computer.com/ModernComputer/Basis/images/Engelbart.jpg)


#### Изменение размера изображений

Пример уменьшения размера верхнего изображения до 100 пикселей в ширину:

![Энгельбарт|100](https://history-computer.com/ModernComputer/Basis/images/Engelbart.jpg)


### Ссылки

#### Внешние ссылки

Ссылки в формате Markdown можно использовать как для отсылки к внешним объектам вроде веб-страниц, так и к внутренним страницам или изображениям.

http://obsidian.md — создаются автоматически!
[Obsidian](http://obsidian.md)


Вы так же можете вставить ссылку на файл указав имя хранилища и имя файла, без полного пути до него:

[Ссылка на файл](obsidian://open?vault=MainVault&file=MyNote.md)


#### Экранирование

Если в ссылке есть пробелы, они могут быть экранированы. Например, с использованием кода `%20` вместо пробелов:

[Импорт данных](Импорт%20данных)

Или вы можете заключить цель в угловые скобки `<>`:

[Демонстрация слайдов](<Демонстрация слайдов>)


### Цитирование


> Люди сталкиваются со всё более сложными и неотложными проблемами, и их эффективность в решении этих проблем имеет решающее значение для стабильности и дальнейшего прогресса общества.

\- Дуглас Энгельбарт, 1961


### Встроенный код

Текст внутри `обратных кавычек` в строке будет отображаться как код. 


### Блоки кода

Подсветка синтаксиса кода поддерживается путем указания языка после первых трех обратных кавычек. Для подсветки мы используем библиотеку PrismJS, список поддерживаемых языков можно найти [на их сайте](https://prismjs.com/#supported-languages).

<pre><code>```js
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}
```</code></pre>

```js
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}
```

	Текст с отступом, сделанным с помощью табуляции, будет выглядеть как блок кода в области предварительного просмотра.


### Список задач

- [x] поддерживаются #теги, [ссылки](), **форматирование**
- [x] используется синтаксис списка (поддерживаются упорядоченный или не упорядоченный списки)
- [x] это завершенная задача
- [?] это тоже завершенная задача (работает с любым символом)
- [ ] это незавершенная задача
- [ ] задачи в области предварительного просмотра помечаются завершенными при нажатии на чекбокс


### Таблицы

Вы можете создавать таблицы из списков слов. Шапка таблицы (первая строка) отделяется от остальных строк дефисами `-`. Столбцы разделяются вертикальной чертой `|`:

Первый заголовок | Второй заголовок
------------ | ------------
Первый заголовок | Содержимое второй ячейки
Содержимое первой колонки | Содержимое второй колонки

В таблицах поддерживается выравнивание | Пример выравнивания
:------------|------------:
по краю с использованием двоеточия `:` | по правому краю

В таблицах работаю ссылки. Если в ссылке используется вертикальная черта `|`, она должна быть изолирована символом `\`, чтобы не быть распознанной как элемент таблицы.

Первый заголовок | Второй заголовок
------------ | ------------
[[Форматирование заметок\|Форматирование]] | [[Сочетания клавиш\|Горячие клавиши]]


### Зачеркивание

Любой текст заключенный в двойные тильды (например, ~~так~~) будет отображаться как зачеркнутый.


### Подсветка

Используя двойные знаки равенства можно ==подсветить текст==.


### Сноски

Пример простой сноски[^1] и пример сноски подлиннее[^большая_сноска].

[^1]: со смыслом!

[^большая_сноска]: с несколькими абзацами и кодом.

    Делайте отступ перед абзацем, чтобы включить его в сноску.

    `{ мой код }`

    Абзацев может быть сколько угодно.

```md
Сноски также можно оставлять прямо в тексте.^[обратите внимание, что карет `^` при этом выносится за скобки.]
```

Сноски также можно оставлять прямо в тексте.^[обратите внимание, что карет `^` при этом выносится за скобки.]

### Математические формулы

Для отображения формулы в отдельном блоке, необходимо заключить ее в двойные `$$`:

$$\begin{vmatrix}a & b\\
c & d
\end{vmatrix}=ad-bc$$

Так же возможно отображение формулы внутри строки $e^{2i\pi} = 1$.


### Комментарии

Используйте двойные `%%` для вложения комментариев, которые будут распознаны как текст Markdown, но не будут показаны в режиме предварительного просмотра.

Комментарий внутри текста: %%скрытый комментарий%% (который, не виден в режиме предварительного просмотра)

Скрытый блок с комментариями: (который, так же не виден в режиме предварительного просмотра)
%%
Он может содержать
множество строк
%%