Содержание страницы

5. Отличия от разметки LaTeX¶Differences to the LaTeX markup

Хотя язык разметки другой, большинство концепций и типов разметки из старой документации LaTeX сохранены – окружения как директивы reST, встроенные команды как роли reST и так далее.

Однако есть несколько отличий в том, как они работают, отчасти из-за различий в языках разметки, отчасти из-за улучшений в Sphinx. В этом разделе перечислены эти отличия, чтобы дать тем, кто знаком со старым форматом, быстрый обзор того, с чем они могут столкнуться.

5.1. Встроенная разметка¶Inline markup

Были внесены следующие изменения во встроенную разметку:

Роли перекрёстных ссылок

Большинство следующих семантических ролей ранее существовали как встроенные команды, но не делали ничего, кроме форматирования содержимого как кода. Теперь они создают перекрёстные ссылки на известные цели (некоторые имена также были сокращены):

mod (ранее refmodule или module)

func (ранее function)

data (новое)

константа

класс

meth (ранее method)

attr (ранее member)

exc (ранее исключение)

cdata

cfunc (ранее cfunction)

cmacro (ранее csimplemacro)

ctype

Также отличается обработка func и meth: ранее скобки добавлялись к имени вызываемого объекта (как \func{str()}), теперь они добавляются системой сборки – добавление их в исходном коде приведёт к двойным скобкам. Это также означает, что запись :func:`str(object)` не будет работать как ожидается – используйте вместо неё ``str(object)``!
Встроенные команды, реализованные как директивы

Раньше это были встроенные команды в LaTeX, но теперь это директивы в reST:

устарело

versionadded

versionchanged

Они используются следующим образом:
```
.. deprecated:: 2.5
   Reason of deprecation.
```
Кроме того, к тексту versionadded и versionchanged не добавляется точка.

note

warning

Они используются следующим образом:
```
.. note::

   Content of note.
```
Прочие изменённые команды

Команда samp ранее форматировала код и добавляла вокруг него кавычки. Однако роль samp теперь использует новую систему подсветки, как и file:

:samp:`open({filename}, {mode})` даёт в результате open(filename, mode)
Удалённые команды

Это были команды LaTeX, но теперь они недоступны в качестве ролей:

bfcode

character (использовать ``'c'``)

citetitle (использовать `Title <URL>`_)

code (использовать ``code``)

email (адрес просто указывается в основном тексте)

filenq

filevar (использовать функцию {...} подсветки для file)

programopt, longprogramopt (использовать option)

ulink (использовать `Title <URL>`_)

url (URL просто указывается в основном тексте)

var (использовать *var*)

infinity, plusminus (использовать символ Unicode)

shortversion, version (использовать подстановки |version| и |release|)

emph, strong (использовать разметку reST)
Экранирование обратной косой черты

В reST обратную косую черту нужно экранировать в обычном тексте и в содержимом ролей. Однако в литералах кода и блоках литералов экранировать её не нужно. Пример: :file:`C:\\Temp\\my.tmp` против ``open("C:\Temp\my.tmp")``.

5.2. Информационные единицы¶Information units

Информационные единицы (окружения ...desc) стали директивами reST. Эти изменения информационных единиц следует отметить:

Новые названия

«desc» удалён из каждого названия. Кроме того, данные директивы имеют новые названия:

cfunction (ранее cfuncdesc)

cmacro (ранее csimplemacrodesc)

исключение (ранее excdesc)

function (ранее funcdesc)

attribute (ранее memberdesc)

Окружения classdesc* и excclassdesc удалены, а директивы class и исключение поддерживают классы, документированные с аргументами конструктора и без.
Несколько объектов

Эквивалент команд ...line:
```
.. function:: do_foo(bar)
              do_bar(baz)

   Description of the functions.
```
То есть просто указывается одна сигнатура на строку, с одинаковым отступом.
Аргументы

Команды optional не существует. Просто укажите сигнатуры функций так, как они должны отображаться в выводе:
```
.. function:: open(filename[, mode[, buffering]])

   Description.
```
Примечание: разметка в сигнатуре не поддерживается.
Индексирование

Окружения ...descni были удалены. Чтобы пометить информационный блок как неподходящий для создания индексной записи, используйте параметр noindex следующим образом:
```
.. function:: foo_*
   :noindex:

   Description.
```
Новые информационные блоки

Появились новые универсальные информационные блоки: один называется «describe» и может использоваться для документирования того, что не охвачено другими блоками:
```
.. describe:: a == b

   The equals operator.
```
Остальные:
```
.. cmdoption:: -O

   Describes a command-line option.

.. envvar:: PYTHONINSPECT

   Describes an environment variable.
```

5.3. Структура¶Structure

Документация LaTeX была разделена на несколько руководств верхнего уровня. Теперь все файлы являются частью единого дерева документации, на что указывают директивы toctree в исходниках (хотя отдельные форматы вывода могут снова разбивать их на части). Каждая директива toctree встраивает другие файлы как поддокументы текущего файла (эта структура не обязательно отражается в файловой системе). Файл верхнего уровня – contents.rst.

Однако бо́льшая часть старой структуры каталогов сохранена, каталоги переименованы следующим образом:

api -> c-api
dist -> distutils, при этом единственный TeX-файл был разделён
doc -> documenting
ext -> extending
inst -> installing
lib -> library
mac -> объединён в library, при этом mac/using.tex перемещён в using/mac.rst
ref -> reference
tut -> tutorial, при этом единственный TeX-файл был разделён