ReStructuredText - ReStructuredText

Не путать с Изобразительное State Transfer.
reStructuredText
reStructuredText логотип
Расширение имени файла
.rst
РазработанДэвид Гуджер
изначальный выпуск2 апреля 2002 г.; 18 лет назад (2002-04-02)
Последний релиз
Редакция 8407
(29 октября 2019 г.; 13 месяцев назад (2019-10-29))
Открытый формат ?Всеобщее достояние
Интернет сайтDocutils.readthedocs.io/ en/ sphinx-docs/Пользователь/ первый/быстрый старт.html

reStructuredText (RST, Отдых, или же отдых) - это формат файла для текстовых данных, используемых в основном в Язык программирования Python сообщество для техническая документация.

Он является частью проекта Docutils Python Doc-SIG (Documentation Special Interest Group), направленного на создание набора инструментов для Python, аналогичных Javadoc за Ява или же Обычная старая документация (POD) для Perl. Docutils может извлекать комментарии и информацию из программ Python и форматировать их в различные формы программной документации.[1]

В этом смысле reStructuredText - это облегченный язык разметки разработан так, чтобы (а) обрабатываться программным обеспечением для обработки документации, таким как Docutils, и (б) легко читаться людьми-программистами, которые читают и пишут на Python исходный код.

История

Был ряд проблем с более ранним облегченным языком разметки StructuredText (разработанным Zope ), и reST был разработан для их решения.[2] Имя reStructuredText было выбрано, чтобы указать, что reST является «переработанным, переработанным и переинтерпретированным StructuredText».[3]

reST начал широко использоваться в сообществе Python в 2002 году.[нужна цитата ]

Эталонная реализация

Эталонная реализация reST парсер компонент фреймворка обработки текста Docutils в Язык программирования Python, но доступны и другие парсеры.

Для ReStructured Text не зарегистрирован официальный тип MIME, но есть неофициальный тип. текст / x-rst.[4]

Приложения

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

С 2008 года reST был основным компонентом Python Сфинкс система генерации документов.

Trac также поддерживает reStructuredText,[6] как и GitHub и Bitbucket.

В 2011, Распределенные корректоры, подготовившие тексты для Проект Гутенберг, рассматривала возможность принятия reST в качестве основного формата, из которого можно было бы создавать другие форматы электронных книг.[7][нуждается в обновлении ]

В июле 2016 г. Ядро Linux проект решил перейти от DocBook документация на основе reStructuredText и Сфинкс набор инструментов.[8]

Инструмент сборки программного обеспечения CMake перешел с пользовательского языка разметки на reStructuredText в версии 3.0 для документации.[9]

Примеры разметки reST

Заголовки

Заголовок раздела ============== Заголовок подраздела -----------------

Списки

- Пункт маркированного списка- Второй предмет - Подпункт- Расстояние между элементами разделяет элементы списка* Различные символы маркеров создают отдельные списки- Третий пункт1) Элемент нумерованного списка2) Второй элемент а) Подэлемент, который продолжается долго и, следовательно, должен быть упакован. Обратите внимание на отступ, который должен соответствовать началу текста, а не перечислителю. я) Элементы списка могут даже включать разрывы абзацев.3) Третий пункт#) Другой элемент пронумерованного списка#) Второй предмет

Изображений

.. изображение:: /path/to/image.jpg

Именованные ссылки

Предложение со ссылками на `Википедия`_ и `Архив ядра Linux`_... _Википедия: https://www.wikipedia.org/.. _ Архив ядра Linux: https://www.kernel.org/

Анонимные ссылки

Еще одно предложение с `анонимная ссылка на веб-сайт Python`__.__ https://www.python.org/

Примечание: именованные ссылки и анонимные ссылки заключаются в серьезные акценты (`), а не в апострофы (').

Буквальные блоки

::  какой-то буквальный текстЭто также можно использовать в конце абзаца, например::  еще немного буквального текста.. код:: python print («Директива буквального блока, явно помеченная как код Python»)

Смотрите также

Рекомендации

  1. ^ Мерц, Дэвид (2003-02-01). «Вопросы XML: reStructuredText». IBM developerWorks. Получено 2016-10-05.
  2. ^ Гуджер, Дэвид (2016-05-24). "reStructuredText: синтаксис разметки и компонент синтаксического анализатора Docutils". Docutils Project. Получено 2016-10-05.
  3. ^ Гуджер, Дэвид (26.02.2016). «FAQ по Docutils (часто задаваемые вопросы)». Docutils Project. Получено 2016-10-05.
  4. ^ «Какой официальный тип MIME для данных reStructuredText? В FAQ по Docutils». Docutils Project. Получено 2017-12-20.
  5. ^ Гуджер, Дэвид (2002-04-02). "PEP 287 - формат строки документа reStructuredText". Фонд программного обеспечения Python. Получено 2016-10-05.
  6. ^ "Поддержка reStructuredText в Trac". Trac. 2016-09-13. Получено 2016-10-05.
  7. ^ Ньюби, Грег (2011-01-08). «Протокол заседания 11 декабря 2010 г.». Распределенные корректоры. Получено 2011-01-08.
  8. ^ «Документация ядра с Sphinx, часть 1: как мы сюда попали». LWN.net. 2016-07-06. Получено 2016-10-27.
  9. ^ «Примечания к выпуску CMake 3.0.0». Kitware, Inc. 10 июня 2014 г.. Получено 2016-10-05.

внешняя ссылка