Sphinx содержит дополнительные конструкции разметки, значительно расширяющие функционал, но которые не поддерживаются стандартной разметкой reStructuredText.
Стандартная разметка ReST (reStructuredText)
поддерживает создание в отдельных документах автоматического содержания на основе заголовков. Sphinx расширяет данную функцию и позволяет автоматически создавать общее оглавление для группы документов.
Файл index.rst
обычно содержит автоматическое оглавление, созданное командой .. toctree::
:
.. toctree::
:maxdepth: 2
:numbered:
:hidden:
имя_документа1
имя_документа1
имя_документа1
Команда .. toctree::
имеет несколько параметров:
:maxdepth:
— уровни заголовков, включаемых в оглавление;:numbered:
— нумерация всех пунктов оглавления;:hidden:
— позволяет скрыть оглавление.
После параметров через пустую строку, с отступами, идут названия включаемых файлов, без расширения. Данные названия будут автоматически преобразованы в заголовки разделов.
Параметр :maxdepth:
не распространяется на LaTeX-документы. Глубина оглавления в LaTeX контролируется его внутренним счетчиком, который можно настроить в файле конфигурации Sphinx conf.py
, указав в преамбуле значение \setcounter{tocdepth}{2}
.
Параметр :hidden:
позволяет Sphinx'у быть в курсе структуры документа, но при этом не отображать оглавление. Удобно, если ссылки на разделы будут указаны, например, на боковой панели.
Подробнее об автоматическом оглавлении в Sphinx смотрите в разделе «The TOC tree» официальной документации Sphinx.
Sphinx поддерживает вставку примеров исходного когда с подсветкой синтаксиса на разных языках программирования. Вставка листингов осуществляется командой .. code-block:: <название яыка>
: :
.. code-block:: python
:emphasize-lines: 1-3,5
def some_function():
interesting = False
print 'This line is highlighted.'
print 'This one is not...'
print '...but this one is.'
Результат:
def some_function():
interesting = False
print 'This line is highlighted.'
print 'This one is not...'
print '...but this one is.'
Пример вставки листинга на языке Ruby: :
.. code-block:: ruby
:linenos:
Some more Ruby code.
Результат:
Some more Ruby code.
Команда .. code-block::
имеет следующие параметры:
:linenos:
— добавляет нумерацию строк;:emphasize-lines:
— включает подсветку отдельных строк, допускается перечисление одиночных строк через запятую или групп строк через тире.
Также Sphinx поддерживает вставку кода непосредственно из файла скрипта: :
.. literalinclude:: example.rb
:language: ruby
:emphasize-lines: 3,9-11
:encoding: latin-1
:start-after: 2
:end-before: 15
:linenos:
Параметры :start-after:
и :end-before:
позволяют указать с какой по какую строки приводить листинг.
Дополнительную информацию смотрите в разделе «Showing code examples» официальной документации Sphinx.
Вставка формул в предложение: :: Формула в предложении a2 + b2 = c2.
Формула в предложении a2 + b2 = c2.
Выравнивание формул относительно знака равно осуществляется с помощью знака &
. Перенос строк с помощью \\
: :: .. math:
(a + b)^2 &= (a + b)(a + b) \\
&= a^2 + 2ab + b^2
Для нумерации формул необходимо использовать параметр :label:
: :: .. math:: e^{ipi} + 1 = 0 🏷️ euler
Формула
euler
представляет собой Тождество Эйлера.
eiπ + 1 = 0
Формула euler
представляет собой Тождество Эйлера.
Расположение номера относительно формулы зависит от настроек HTML-темы.
Подробнее смотрите главу Math support in Sphinx официальной документации Sphinx.
Подробнее смотрите раздел ext-math-label
. Также смотрите раздел math-errors2-label
.
Для вставки графиков используются дополнительные расширения, список которых приведен на странице Sphinx Extensions официальной документации Sphinx.
Также смотрите раздел ext-label
.
Sphinx позволяет создавать перекрестные ссылки между отдельными .rst файлами, подключенными в файле index.rst
.
Для того, чтобы создать ссылку на другой раздел, необходимо сначала установить закладку перед этим разделом. Например, для ссылки на пункт table-label
из раздела rst-markup-label
я использовал следующие команды: :
.. _rst-markup-label:
Стандартный синтаксис разметки reStructuredText
===============================================
.. _table-label:
Таблицы
~~~~~~~
Таким образом, я установил закладки. Теперь можно сослаться на них: :
Например, для ссылки на пункт :ref:`table-label` из
раздела :ref:`rst-markup-label` я использовал следующие команды:
Ссылка осуществляется с помощью команды :ref:
и названия закладки в обратных кавычках. Закладки автоматически преобразуются в названия разделов, поэтому между закладкой и заголовком ничего не должно находиться.
Аналогичным образом осуществляется ссылка на изображения и таблицы. Для формул используется немного иной синтакси.
Для ссылки на изображение перед ним также надо поставить закладку, которая автоматически будет преобразовываться в подпись изображения:
.. _my-favicon:
.. figure:: img/favicon.png
:scale: 300 %
:align: center
:alt: Альтернативный текст
Подпись изображения
Легенда изображения.
Теперь сделаем ссылку на изображение my-favicon
: :
Теперь сделаем ссылку на изображение :ref:`my-favicon`:
Ссылки на таблицы осуществляются по тому же принципу. Сначала перед таблицей устанавливается закладка, которая потом автоматически преобразуется в название таблицы. :
.. _cvs-table:
.. csv-table:: CSV-таблица
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
Ссылка на cvs-table
: :
Ссылка на :ref:`cvs-table`:
Ссылка на формулы осуществляется немного иным способом, с помощью команды :eq:
. Подробнее смотрите пункт Нумерация формул.
Sphinx позволяет создавать глоссарий с автоматической сортировкой. Элементы глоссария также автоматически попадают в алфавитный указатель. :
.. glossary::
:sorted:
Трансценденция
Философский термин, характеризующий то, что
принципиально недоступно опытному познанию
или не основано на опыте.
Бозон
Частица с целым значением спина.
Результат:
- Трансценденция
Философский термин, характеризующий то, что принципиально недоступно опытному познанию или не основано на опыте.
- Бозон
Частица с целым значением спина.
За автоматическую сортировку отвечает параметр :sorted:
.
Аббревиатуры вставляются следующим образом, например, LIFO (last-in, first-out)
: :
:abbr:`LIFO (last-in, first-out)`
Для обозначения пунктов меню используются команды menuselection
и guilabel
: :
:menuselection:`Файл --> О&ткрыть`
:guilabel:`&Открыть`
Файл --> О&ткрыть
&Открыть
Символ &
устанавливает в зависити от темы HTML следующему за ним символу нижнее подчеркивание.
Sphinx вводит ряд автозамен, которые не требуют объявления, их значения берутся из конфигурационного файла conf.py
. :
Номер релиза: |release|
Номер версии: |version|
Текущая дата: |today|
Номер релиза:
Номер версии:
Текущая дата:
О настройке этих параметров смотрите в пунктах versions-conf
и date-conf
.
.. seealso:: Блок с дополнительной информацией.
Блок с дополнительной информацией. См. также admonitions-label
.
Боковая врезка добавляетяс командой .. sidebar::
:
.. sidebar:: Боковая врезка
Оформление врезки зависит от используемой HTML-темы.
Боковая врезка
Оформление врезки зависит от используемой HTML-темы.
Рубрики создаютcя командой .. rubric::
и используются для создания заголовков, не включаемых в общее содержание. :
.. rubric:: Пример рубрики
Текст рубрики
Пример рубрики
Текст рубрики
.. hlist::
:columns: 3
* A list of
* short items
* that should be
* displayed
* horizontally
- A list of
- short items
- that should be
- displayed
- horizontally
Note
Здесь приведен не полный перечень дополнительных конструкций Sphinx, подробнее в разделе Inline markup и Paragraph-level markup официальной документации Sphinx.
Для создания документации по языкам программирования Sphinx имеет специальные команды. Например, для описания тех или иных функций языка может использоваться команда .. function::
: :
.. function:: pyfunc()
Описание функции Python.
pyfunc()
Описание функции Python.
Эта команда автоматически добавляет функцию в genindex
.
Похожие конструкции имеются и для других языков программирования, подробнее смотрите раздел Sphinx Domains официальной документации Sphinx.
Sphinx автоматически генерирует алфавитный указатель, на основе команд .. glossary::
, .. function::
и некоторых других (подробнее смотрите раздел Sphinx Domains официальной документации Sphinx).
Но можно и вручную внести элементы в алфавитный указатель с помощью команды .. index::
.
.. index:: Указатель
Указатель
Главная запись индекса предваряется восклицательным знаком: :
.. index:: ! Указатель
Короткая запись: :
.. index:: BNF, grammar, syntax, notation
Ссылка на указатель имеет вид :ref:`genindex
(:ref:`genindex).