ReStructuredText

ReStructuredText
Изображение логотипа
Расширение .rst
MIME-тип text/x-rst
Тип формата текстовые форматы
Сайт docutils.sourceforge.io/… (англ.)

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

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

История

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

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

В результате в 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: 

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. Дата обращения: 29 сентября 2012. Архивировано 17 сентября 2012 года.
  2. ↑ Mertz, David XML Matters: reStructuredText. IBM developerWorks (1 февраля 2003). Дата обращения: 28 декабря 2011. Архивировано из оригинала 26 октября 2012 года.
  3. ↑ Sphinx documentation generator. Дата обращения: 29 сентября 2012. Архивировано из оригинала 20 мая 2012 года.
  4. ↑ Projects using Sphinx. Дата обращения: 29 сентября 2012. Архивировано из оригинала 15 сентября 2012 года.
  5. ↑ GitHub Markup. Дата обращения: 29 сентября 2012. Архивировано 20 июля 2012 года.
  6. ↑ PG Monthly Newsletter (2012-03-07). Дата обращения: 29 сентября 2012. Архивировано 5 сентября 2014 года.
  7. ↑ RST. Дата обращения: 29 сентября 2012. Архивировано 9 июня 2012 года.
  8. ↑ Thomas Bitterman. Mastering IPython 4.0. — Packt Publishing, 2016.

Ссылки