Расширение имени файла | .rst |
---|---|
Тип интернет-СМИ | текст / x-rst |
Разработано | Дэвид Гуджер |
Первый выпуск | 2 апреля 2002 г . |
Последний релиз | Ревизия 8407 (29 октября 2019 г . ) |
Открытый формат ? | Всеобщее достояние |
Веб-сайт | Docutils |
reStructuredText ( RST , ReST или reST ) - это формат файла для текстовых данных, используемый в основном сообществом языков программирования Python для технической документации .
Он является частью проекта Docutils группы Python Doc-SIG (Documentation Special Interest Group), нацеленного на создание набора инструментов для Python, аналогичных Javadoc для Java или простой старой документации (POD) для Perl . Docutils может извлекать комментарии и информацию из программ Python и форматировать их в различные формы программной документации. [1]
В этом смысле reStructuredText - это легкий язык разметки, предназначенный как для (а) обработки с помощью программного обеспечения для обработки документации, такого как Docutils, так и (б) для легкого чтения программистами, которые читают и пишут исходный код Python .
История [ править ]
Был ряд проблем с более ранним облегченным языком разметки StructuredText (разработанным Zope ), и reST был разработан для их решения. [2] Имя reStructuredText было выбрано, чтобы указать, что reST является «переработанным, переработанным и переинтерпретированным StructuredText». [3]
Rest начал видеть значительное использование в сообществе Python в 2002 году [ править ]
Эталонная реализация [ править ]
Эталонная реализация парсера reST является компонентом фреймворка обработки текста Docutils на языке программирования Python , но доступны и другие парсеры.
Для ReStructured Text не зарегистрирован официальный тип пантомимы, но есть неофициальный text/x-rst
. [4]
Приложения [ править ]
reStructuredText обычно используется для технической документации, например, в документации библиотек Python. [5] Однако он подходит для широкого спектра текстов.
С 2008 года reST является основным компонентом системы генерации документов Python Sphinx .
Trac также поддерживает reStructuredText [6], как и GitHub и Bitbucket .
В 2011 году компания Distributed Proofreaders , которая готовила тексты для Project Gutenberg , рассматривала возможность принятия reST в качестве базового формата, из которого можно было бы создавать другие форматы электронных книг. [7] [ требуется обновление ]
В июле 2016 года проект ядра Linux решил перейти от документации на основе DocBook к reStructuredText и инструментарию Sphinx . [8]
Инструмент сборки программного обеспечения CMake перешел с пользовательского языка разметки на reStructuredText в версии 3.0 для документации. [9]
Примеры разметки reST [ править ]
Заголовки [ править ]
Заголовок раздела==============Заголовок подраздела-----------------
Списки [ править ]
- Элемент маркированного списка - Второй элемент - Подпункт- Интервал между элементами разделяет элементы списка* Различные символы маркеров создают отдельные списки- Третий пункт1) Элемент нумерованного списка2) Второй пункт а) Подпункт, который продолжается долго и поэтому требует быть завернутым. Обратите внимание на отступ, который должен соответствовать началу текста, а не счетчик. i) Элементы списка могут даже включать разрывы абзацев.3) Третий пункт#) Другой элемент пронумерованного списка#) Второй элемент
Изображения [ редактировать ]
.. image :: /path/to/image.jpg
Именованные ссылки [ править ]
Предложение со ссылками на `Wikipedia`_ и ` ядра archive`_ Linux ... _Википедия: https://www.wikipedia.org/ .. _Архив ядра Linux: https://www.kernel.org/
Анонимные ссылки [ править ]
Еще одно предложение с `анонимной ссылкой на веб-сайт Python`__ .__ https://www.python.org/
NB: именованные ссылки и анонимные ссылки заключаются в серьезные акценты (`), а не в апострофы (').
Литеральные блоки [ править ]
:: какой-то буквальный текстЭто также можно использовать в конце абзаца, например : еще немного буквального текста.. code :: python print ("Директива буквального блока, явно помеченная как код Python")
См. Также [ править ]
- Сравнение языков разметки документов
- Сравнение генераторов документации
- Сравнение программного обеспечения для ведения заметок
Ссылки [ править ]
- ^ Мерц, Дэвид (2003-02-01). «Вопросы XML: reStructuredText» . IBM developerWorks . Проверено 5 октября 2016 .
- ^ Гуджер, Дэвид (2016-05-24). «reStructuredText: синтаксис разметки и компонент парсера Docutils» . Docutils Project . Проверено 5 октября 2016 .
- ^ Goodger, Дэвид (2016-02-26). «FAQ по Docutils (часто задаваемые вопросы)» . Docutils Project . Проверено 5 октября 2016 .
- ^ «Какой официальный тип MIME для данных reStructuredText? В FAQ по Docutils» . Docutils Project . Проверено 20 декабря 2017 .
- ^ Гуджер, Дэвид (2002-04-02). «PEP 287 - формат строки документа reStructuredText» . Фонд программного обеспечения Python . Проверено 5 октября 2016 .
- ^ "Поддержка reStructuredText в Trac" . Trac . 2016-09-13 . Проверено 5 октября 2016 .
- ^ Ньюби, Грег (2011-01-08). «Протокол заседания 11 декабря 2010 года» . Распределенные корректоры . Проверено 8 января 2011 .
- ^ «Документация ядра с Sphinx, часть 1: как мы сюда попали» . LWN.net. 2016-07-06 . Проверено 27 октября 2016 .
- ^ «Примечания к выпуску CMake 3.0.0» . Kitware, Inc. 2014-06-10 . Проверено 5 октября 2016 .
Внешние ссылки [ править ]
- Официальный сайт reStructuredText со справочными страницами