реструктурированныйтекст
 | |
| Расширение имени файла |
.первый |
|---|---|
| Тип интернет-СМИ | текст/первый раз |
| Разработано | Дэвид Гуджер |
| Первоначальный выпуск | 1 июня 2001 г [1] |
| Последний выпуск | Редакция 8407 29 октября 2019 г |
| Открытый формат ? | Общественное достояние |
| Веб-сайт | документы |
reStructuredText ( RST , ReST или reST ) — это формат файла для текстовых данных, используемый в основном в сообществе языков программирования Python для технической документации .
Это часть проекта Docutils группы Python Doc-SIG (Documentation Special Interest Group), направленного на создание набора инструментов для Python, аналогичного Javadoc для Java или Plain Old Documentation (POD) для Perl . Docutils может извлекать комментарии и информацию из программ Python и форматировать их в различные формы программной документации. [2]
В этом смысле reStructuredText — это легкий язык разметки, предназначенный для обработки с помощью программного обеспечения для обработки документации, такого как Docutils, и для легкого чтения людьми-программистами, которые читают и пишут исходный код Python .
История
[ редактировать ]reStructuredText произошел от более раннего облегченного языка разметки под названием StructuredText. [3] (разработано Zope ). У StructuredText был ряд проблем, и для их решения был разработан reST. [4] Название reStructuredText было выбрано, чтобы указать, что reST представляет собой «пересмотренный, переработанный и переосмысленный StructuredText». [5]
Части синтаксиса reST были вдохновлены языком Setext начала 1990-х годов. Элементы общего формата интернет-сообщений RFC822 и форматов Javadoc также рассматривались для включения в проект. [6]
reStructuredText был впервые выпущен в июне 2001 года. [1] Он начал широко использоваться в сообществе Python в 2002 году. [7]
Эталонная реализация
[ редактировать ]Эталонная реализация парсера reST является компонентом платформы обработки текста Docutils на языке программирования Python , но доступны и другие парсеры.
Для reStructuredText не зарегистрировано официального типа MIME , но есть неофициальный. text/x-rst. [8]
Приложения
[ редактировать ]reStructuredText обычно используется для технической документации, например, в документации библиотек Python. [9] Однако он подходит для широкого спектра текстов.
С 2008 года reST является основным компонентом системы генерации документов Python Sphinx .
Trac также поддерживает reStructuredText, [10] как и GitHub и Bitbucket .
В 2011 году компания Distributed Proofreaders , готовившая тексты для Project Gutenberg , рассматривала возможность принятия reST в качестве базового формата, на основе которого можно было бы генерировать другие форматы электронных книг. [11] [ нужно обновить ]
В июле 2016 года проект ядра Linux решил перейти от документации на основе DocBook к reStructuredText и набору инструментов Sphinx . [12] [13] [ циклическая ссылка ]
Инструмент сборки программного обеспечения CMake перешел с собственного языка разметки на reStructuredText в версии 3.0 для документации. [14]
Примеры
[ редактировать ]| Текст с использованием синтаксиса rST | Соответствующий HTML, созданный процессором rST. | Текст, просматриваемый в браузере |
|---|---|---|
================
Document Heading
================
Heading
=======
Sub-heading
-----------
Paragraphs are separated
by a blank line.
|
<h1>Document Heading</h1>
<h2>Heading</h2>
<h3>Sub-heading</h3>
<p>Paragraphs are separated
by a blank line.</p>
|
Абзацы разделены пустой строкой. |
Text attributes *emphasis*, **strong emphasis**, ``monospace``.
Horizontal rule:
----
|
<p>Text attributes <em>emphasis</em>,
<strong>strong emphasis</strong>, <code>monospace</code>.</p>
<p>Horizontal rule:</p>
<hr />
|
Текстовые атрибуты выделения ,
сильный акцент , monospace.
Горизонтальное правило: |
Bullet list:
* apples
* oranges
* pears
Numbered list:
1. lather
2. rinse
3. repeat
Nested lists:
1. fruits
* apple
* banana
2. vegetables
* carrot
* broccoli
|
<p>Bullet list:</p>
<ul>
<li>apples</li>
<li>oranges</li>
<li>pears</li>
</ul>
<p>Numbered list:</p>
<ol>
<li>lather</li>
<li>rinse</li>
<li>repeat</li>
</ol>
<p>Nested lists:</p>
<ol>
<li>fruits
<ul>
<li>apple</li>
<li>banana</li>
</ul>
</li>
<li>vegetables
<ul>
<li>carrot</li>
<li>broccoli</li>
</ul>
</li>
</ol>
|
Список маркеров:
Нумерованный список:
Вложенные списки:
|
An `example <http://example.com>`_.
.. image:: Icon-pictures.png
:alt: Image
If text is indented, it is treated as a block quotation:
Should array indices start at 0 or 1?
My suggested compromise of 0.5 was rejected without, I thought, proper consideration.
-- Stan Kelly-Bootle
reST uses :: at the end of the paragraph prior to a pre-formatted code block::
Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))
| Multi-line text can
| span in tables
| with a pipe character.
|
<p>An <a href="http://example.com">example</a>.</p>
<p><img alt="Image"src="Icon-pictures.png" /></p>
<p>If text is indented, it is treated as a block quotation, and the final attribution line is handled automatically:</p>
<blockquote>
Should array indices start at 0 or 1?
My suggested compromise of 0.5 was rejected without, I thought, proper consideration.
-- Stan Kelly-Bootle</blockquote>
<p>reST uses :: at the end of the paragraph prior to a pre-formatted code block:</p>
<pre class="literal-block">
Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x)))
</pre>
<p>Multi-line text can<br/>span in tables<br/>with a pipe character.</p>
|
Пример .
Если текст имеет отступ, он рассматривается как блочная цитата, а последняя строка атрибуции обрабатывается автоматически:
reST использует :: в конце абзаца перед предварительно отформатированным блоком кода: Y = lambda f: (lambda x: f(x(x)))(lambda x: f(x(x))) Многострочный текст может |
См. также
[ редактировать ]- Сравнение языков разметки документов
- Сравнение генераторов документации
- Сравнение программного обеспечения для заметок
Ссылки
[ редактировать ]- ^ Jump up to: а б «Проект: reStructuredText — Список файлов» . СоурсФордж . Архивировано из оригинала 19 октября 2001 года . Проверено 5 февраля 2023 г.
- ^ Мерц, Дэвид (1 февраля 2003 г.). «XML имеет значение: reStructuredText» . IBM DeveloperWorks . Проверено 5 октября 2016 г.
- ^ «Документация zope.structuredtext» . Прочтите Документы . Проверено 16 августа 2022 г.
- ^ Гуджер, Дэвид (24 мая 2016 г.). «Проблемы со структурированным текстом» . Проект Документилс . Проверено 16 августа 2022 г.
- ^ Гуджер, Дэвид (26 февраля 2016 г.). «Часто задаваемые вопросы по Docutils (часто задаваемые вопросы)» . Проект Документилс . Проверено 5 октября 2016 г.
- ^ Гуджер, Дэвид (2 апреля 2022 г.). «Запись альтернатив синтаксиса reStructuredText» . docutils.sourceforge.io . Проект Документилс . Проверено 16 августа 2022 г.
- ^ «Введение в reStructuredText» . Напишите документы . Проверено 25 июня 2022 г.
- ^ «Какой официальный тип MIME для данных reStructuredText? в FAQ по Docutils» . Проект Документилс . Проверено 20 декабря 2017 г.
- ^ Гуджер, Дэвид (2 апреля 2002 г.). «PEP 287 — формат строки документации reStructuredText» . Фонд программного обеспечения Python . Проверено 5 октября 2016 г.
- ^ «Поддержка reStructuredText в Trac» . Трек . 13 сентября 2016 г. Проверено 5 октября 2016 г.
- ^ Ньюби, Грег (8 января 2011 г.). «Протокол заседания от 11 декабря 2010 года» . Распределенные корректоры . Проверено 8 января 2011 г.
- ^ «Документация ядра Sphinx, часть 1: как мы сюда попали» . LWN.net. 06.07.2016 . Проверено 27 октября 2016 г.
- ^ «Сфинкс. Ядро Linux» . Arc.Ask3.Ru. 2 апреля 2024 г. Проверено 2 апреля 2024 г.
- ^ «Примечания к выпуску CMake 3.0.0» . Kitware, Inc. 10 июня 2014 г. Проверено 5 октября 2016 г.
Внешние ссылки
[ редактировать ]