reStructuredText

Материал из Википедии — свободной энциклопедии
Перейти к: навигация, поиск
ReStructuredText
Расширение

.rst

MIME-тип

text/x-rst[1]

Тип формата

текстовые форматы

reStructuredText (сокращение: ReST, расширение файла: .rst) — облегчённый язык разметки. Хорошо применим для создания простых веб-страниц и других документов, а также в качестве вспомогательного языка при написании комментариев в программном коде. Используется в системе подготовки технической документации Docutils[2], написанной в основном Дэвидом Гуджером (David Goodger)[3]. reStructuredText можно считать потомком легковесных систем разметки StructuredText и Setext. Парсер reStructuredText поддерживает достаточное количество конечных форматов, в том числе PDF, HTML, ODT, LaTeX и формат презентаций S5.

Система документирования Sphinx[4], написанная для нужд документирования языка программирования Python на сайте docs.python.org и построенная на базе Docutils, применяется уже в нескольких десятках проектов[5]. ReST является одним из языков разметки, используемых на github[6], в частности, для README-файлов. Формат имеет статус экспериментального в проекте «Гутенберг»[7][8].

История[править | править код]

Джим Фултон, создатель Zope, придумал язык разметки StructuredText, напоминающий упрощённую разметку WikiWikiWeb. Проблемы StructuredText привели к созданию Дэвидом Гуджером языка разметки, названного ReStructuredText. При создании преследовались следующие цели[9]:

  • Удобочитаемость
  • Ненавязчивость
  • Однозначность
  • Отсутствие сюрпризов
  • Интуитивность
  • Простота
  • Масштабируемость
  • Выразительная мощность
  • Языковая нейтральность
  • Расширяемость
  • Независимость от выходного формата

В результате в 2002 году появился PEP 287 (англ. Python enhancement proposal — предложение по развитию Python) с описанием ReStructuredText.

Пример синтаксиса[править | править код]

 ==================
 Название документа
 ==================
 
 Заголовок
 ---------
 
 Какой-нибудь простой текст, *текст курсивом*, **текст жирным шрифтом** и ссылка_:
 
 * элемент маркированного списка
 * элемент маркированного списка
 
 1. Первый элемент нумерованного списка
 2. Второй элемент нумерованного списка

 .. figure:: http://upload.wikimedia.org/wikipedia/commons/f/f6/Wikipedia-logo-v2-ru.png
 
     Логотип русской Википедии 
 
 .. _ссылка: http://ru.wikipedia.org

Разметка строк документации (внутри утроенных кавычек) в коде на Python[1]:

class Keeper(Storer):

    """
    Keep data fresher longer.

    Extend `Storer`.  Class attribute `instances` keeps track
    of the number of `Keeper` objects instantiated.
    """

    instances = 0
    """How many `Keeper` objects are there?"""

    def __init__(self):
        """
        Extend `Storer.__init__()` to keep track of
        instances.  Keep count in `self.instances` and data
        in `self.data`.
        """
        Storer.__init__(self)
        self.instances += 1

        self.data = []
        """Store data in a list, most recent last."""
...

Примечания[править | править код]

  1. 1 2 PEP 287 — reStructuredText Docstring Format
  2. Mertz, David XML Matters: reStructuredText. IBM developerWorks (1 февраля 2003). Проверено 28 декабря 2011. Архивировано 26 октября 2012 года.
  3. docutils on Ohloh
  4. Sphinx documentation generator
  5. Projects using Sphinx
  6. GitHub Markup
  7. PG Monthly Newsletter (2012-03-07)
  8. RST
  9. Thomas Bitterman. Mastering IPython 4.0. — Packt Publishing, 2016.

Ссылки[править | править код]