fromlatex.md

1> **Источник:** https://python-all.ru/3.0/documenting/fromlatex.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Отличия от разметки LaTeX89Хотя язык разметки другой, большинство концепций и типов разметки из старой документации LaTeX сохранены – окружения как директивы reST, встроенные команды как роли reST и так далее.1011Однако есть несколько отличий в том, как они работают, отчасти из-за различий в языках разметки, отчасти из-за улучшений в Sphinx. В этом разделе перечислены эти отличия, чтобы дать тем, кто знаком со старым форматом, быстрый обзор того, с чем они могут столкнуться.1213## Строчная разметка1415Были внесены следующие изменения во встроенную разметку:1617- **Роли перекрёстных ссылок**1819  Большинство следующих семантических ролей ранее существовали как встроенные команды, но не делали ничего, кроме форматирования содержимого как кода. Теперь они создают перекрёстные ссылки на известные цели (некоторые имена также были сокращены):2021  *mod*2223  (ранее2425  *refmodule*2627  или2829  *module*3031  )3233  *func*3435  (ранее3637  *function*3839  )4041  *data*4243  (новое)4445  *константа*4647  *класс*4849  *meth*5051  (ранее5253  *method*5455  )5657  *attr*5859  (ранее6061  *member*6263  )6465  *exc*6667  (ранее6869  *исключение*7071  )7273  *cdata*7475  *cfunc*7677  (ранее7879  *cfunction*8081  )8283  *cmacro*8485  (ранее8687  *csimplemacro*8889  )9091  *ctype*9293  Также отличается обработка *func* и *meth*: ранее скобки добавлялись к имени вызываемого объекта (как `\func{str()}`), теперь они добавляются системой сборки – добавление их в исходном коде приведёт к двойным скобкам. Это также означает, что запись `` :func:`str(object)` `` не будет работать как ожидается – используйте вместо неё `` ``str(object)`` ``!94- **Встроенные команды, реализованные как директивы**9596  Раньше это были встроенные команды в LaTeX, но теперь это директивы в reST:9798  *устарело*99100  *добавлено в версии*101102  *изменено в версии*103104  Они используются следующим образом:105106  ```rest107  .. deprecated:: 2.5108     Reason of deprecation.109  ```110111  Кроме того, к тексту *versionadded* и *versionchanged* не добавляется точка.112113  *примечание*114115  *предупреждение*116117  Они используются следующим образом:118119  ```rest120  .. note::121122     Content of note.123  ```124- **Прочие изменённые команды**125126  Команда *samp* ранее форматировала код и добавляла вокруг него кавычки. Однако роль *samp* теперь использует новую систему подсветки, как и *file*:127128  > `` :samp:`open({filename}, {mode})` `` даёт в результате `open(filename, mode)`129- **Удалённые команды**130131  Это были команды LaTeX, но теперь они недоступны в качестве ролей:132133  *bfcode*134135  *character*136137  (использовать138139  `` ``'c'`` ``140141  )142143  *citetitle*144145  (использовать146147  `` `Title <URL>`_ ``148149  )150151  *code*152153  (использовать154155  `` ``code`` ``156157  )158159  *email*160161  (адрес просто указывается в основном тексте)162163  *filenq*164165  *filevar*166167  (использовать функцию168169  `{...}`170171  подсветки для172173  *file*174175  )176177  *programopt*178179  ,180181  *longprogramopt*182183  (использовать184185  *option*186187  )188189  *ulink*190191  (использовать192193  `` `Title <URL>`_ ``194195  )196197  *url*198199  (URL просто указывается в основном тексте)200201  *var*202203  (использовать204205  `*var*`206207  )208209  *infinity*210211  ,212213  *plusminus*214215  (использовать символ Unicode)216217  *shortversion*218219  ,220221  *version*222223  (использовать подстановки224225  `|version|`226227  и228229  `|release|`230231  )232233  *emph*234235  ,236237  *strong*238239  (использовать разметку reST)240- **Экранирование обратной косой черты**241242  В reST обратную косую черту нужно экранировать в обычном тексте и в содержимом ролей. Однако в литералах кода и блоках литералов экранировать её не нужно. Пример: `` :file:`C:\\Temp\\my.tmp` `` против `` ``open("C:\Temp\my.tmp")`` ``.243244## Информационные единицы245246Информационные единицы (окружения *...desc*) стали директивами reST. Эти изменения информационных единиц следует отметить:247248- **Новые названия**249250  «desc» удалён из каждого названия. Кроме того, данные директивы имеют новые названия:251252  *cfunction*253254  (ранее255256  *cfuncdesc*257258  )259260  *cmacro*261262  (ранее263264  *csimplemacrodesc*265266  )267268  *исключение*269270  (ранее271272  *excdesc*273274  )275276  *function*277278  (ранее279280  *funcdesc*281282  )283284  *attribute*285286  (ранее287288  *memberdesc*289290  )291292  Окружения *classdesc\** и *excclassdesc* удалены, а директивы *class* и *исключение* поддерживают классы, документированные с аргументами конструктора и без.293- **Несколько объектов**294295  Эквивалент команд *...line*:296297  ```rest298  .. function:: do_foo(bar)299                do_bar(baz)300301     Description of the functions.302  ```303304  То есть просто указывается одна сигнатура на строку, с одинаковым отступом.305- **Аргументы**306307  Команды *optional* не существует. Просто укажите сигнатуры функций так, как они должны отображаться в выводе:308309  ```rest310  .. function:: open(filename[, mode[, buffering]])311312     Description.313  ```314315  Примечание: разметка в сигнатуре не поддерживается.316- **Индексирование**317318  Окружения *...descni* были удалены. Чтобы пометить информационный блок как неподходящий для создания индексной записи, используйте параметр *noindex* следующим образом:319320  ```rest321  .. function:: foo_*322     :noindex:323324     Description.325  ```326- **Новые информационные блоки**327328  Появились новые универсальные информационные блоки: один называется «describe» и может использоваться для документирования того, что не охвачено другими блоками:329330  ```rest331  .. describe:: a == b332333     The equals operator.334  ```335336  Остальные:337338  ```rest339  .. cmdoption:: -O340341     Describes a command-line option.342343  .. envvar:: PYTHONINSPECT344345     Describes an environment variable.346  ```347348## Структура349350Документация LaTeX была разделена на несколько руководств верхнего уровня. Теперь все файлы являются частью единого дерева документации, на что указывают директивы *toctree* в исходниках (хотя отдельные форматы вывода могут снова разбивать их на части). Каждая директива *toctree* встраивает другие файлы как поддокументы текущего файла (эта структура не обязательно отражается в файловой системе). Файл верхнего уровня – `contents.rst`.351352Однако бо́льшая часть старой структуры каталогов сохранена, каталоги переименованы следующим образом:353354- `api` -\> `c-api`355- `dist` -\> `distutils`, при этом единственный TeX-файл был разделён356- `doc` -\> `documenting`357- `ext` -\> `extending`358- `inst` -\> `installing`359- `lib` -\> `library`360- `mac` -\> объединён в `library`, при этом `mac/using.tex` перемещён в `using/mac.rst`361- `ref` -\> `reference`362- `tut` -\> `tutorial`, при этом единственный TeX-файл был разделён363