> **Источник:** https://python-all.ru/3.1/documenting/fromlatex.html
>
> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.

---

# 5. Отличия от разметки LaTeX

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

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

## 5.1. Встроенная разметка

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

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

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

  *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*

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

  ```rest
  .. deprecated:: 2.5
     Reason of deprecation.
  ```

  Кроме того, к тексту *versionadded* и *versionchanged* не добавляется точка.

  *note*

  *warning*

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

  ```rest
  .. 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. Информационные единицы

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

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

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

  *cfunction*

  (ранее

  *cfuncdesc*

  )

  *cmacro*

  (ранее

  *csimplemacrodesc*

  )

  *исключение*

  (ранее

  *excdesc*

  )

  *function*

  (ранее

  *funcdesc*

  )

  *attribute*

  (ранее

  *memberdesc*

  )

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

  Эквивалент команд *...line*:

  ```rest
  .. function:: do_foo(bar)
                do_bar(baz)

     Description of the functions.
  ```

  То есть просто указывается одна сигнатура на строку, с одинаковым отступом.
- **Аргументы**

  Команды *optional* не существует. Просто укажите сигнатуры функций так, как они должны отображаться в выводе:

  ```rest
  .. function:: open(filename[, mode[, buffering]])

     Description.
  ```

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

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

  ```rest
  .. function:: foo_*
     :noindex:

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

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

  ```rest
  .. describe:: a == b

     The equals operator.
  ```

  Остальные:

  ```rest
  .. cmdoption:: -O

     Describes a command-line option.

  .. envvar:: PYTHONINSPECT

     Describes an environment variable.
  ```

## 5.3. Структура

Документация 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-файл был разделён