Хотите верьте, хотите нет, но проект Python на самом деле предоставляет нам способ сделать это с помощью различных файлов Makefile. Файлы используют проект Python Sphinx для создания файла texi, который makeinfo может затем преобразовать в info, формат, который Emacs использует для документации.
Помимо Python3000, эти инструкции требуют GNU Make и Texinfo. Они включены в большинство дистрибутивов Linux. В разных дистрибутивах могут использоваться разные соглашения об именах. Обратитесь к документации вашего дистрибутива за соответствующими именами пакетов. Для дистрибутивов на основе Debian:
# install make to utilize the Makefiles provided by the Python project
~/$ sudo apt-get install make
# install texinfo for the `makeinfo` command
~/$ sudo apt-get install texinfo
Имена пакетов обычно похожи для систем, отличных от Debian. Для пользователей Windows я рекомендую WSL или создать виртуальную машину .
1. Загрузите документацию
Перейдите по адресу https://www.python.org/ftp/python/ и загрузите tarball для вашей версии Python. Это будет выглядеть так:
https://www.python.org/ftp/python/3.7.9/Python-3.7.9.tar.xz
Вы можете использовать wget для загрузки архива и tar для его распаковки. Опции x и f предназначены для извлечения файла:
# download the tarball
~/$ wget https://www.python.org/ftp/python/3.7.9/Python-3.7.9.tar.xz
# extract the tarball
~/$ tar xf Python-3.7.9.tar.xz
2. Запустите make venv в Python-X.Y.Z/Doc
Sphinx требует больше зависимостей, чем входит в базовую pip установку. К счастью, проект Python предоставляет Makefile для создания необходимой среды. Подробности см. на Makefile.
# Navigate to the Doc/ directory
~/$ cd Python-3.7.9/Doc
# "create a venv with necessary tools"
~/Python-3.7.9/Doc$ make venv
# activate the venv created by make
~/Python-3.7.9/Doc$ source venv/bin/activate
3. Запустите sphinx-build
Теперь, когда правильная среда настроена, мы можем запустить Sphinx. Этот вызов создает кеш, используемый во время генерации с опцией -d. Файлы документации, найденные в текущем каталоге, конвертируются компоновщиком texinfo и выводятся в build/texinfo:
# -b: Use the textinfo builder
# -d: Create "doctree pickles" cache in doctrees/
# Use the current directory as source
# Output to build/texinfo
(venv) ~/Python-3.7.9/Doc$ sphinx-build -b texinfo -d build/doctrees . build/texinfo
4. Используйте makeinfo для создания файла info
Опять же, сопровождающие Python дали нам то, что нам нужно (даже если они плохо задокументировали это). Предыдущая команда создала файл texi вместе с другим файлом Makefile. Makefile вызывает makeinfo.
# Navigate to the output directory
(venv) ~/Python-3.7.9/Doc$ cd build/texinfo
# Run the generated Makefile
(venv) ~/Python-3.7.9/Doc/build/texinfo$ make
# Hark, unto us an info file is born
(venv) ~/Python-3.7.9/Doc/build/texinfo$ ls
Makefile python-figures python.info python.texi
Подобно Индиане Джонсу, вы видите Святой Грааль. Многие погибли в этом путешествии; ты победил. Найдите минутку, чтобы отпраздновать.
Примечание. Преобразование makeinfo приводит к ошибкам. Неважно, говорю. Желанный info получен и я жадно пью из него.
5. Загрузите python.info в Emacs...
Проверьте C-h v Info-default-directory-list, где хранятся информационные файлы. Поместите туда файл python.info. В этом каталоге также должен быть файл с именем dir (если его там нет, не волнуйтесь, он будет создан). Это texinfo сгенерированный файл, содержащий список узлов. Хотя это можно изменить вручную, это чревато ошибками1.
Запустите update-info-dir в любом каталоге, который вы поместили python.info обновить dir, чтобы включить новый файл.
Для получения полной информации о системе texinfo см. https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Installing-an-Info-File.html.
Если вам лень, вы также можете просто открыть файл python.info и включить M-x Info-mode.
1Помимо человеческих ошибок, таких как опечатка в ссылке, проблемы могут возникнуть из-за неправильного формата файлов dir.
person
Lorem Ipsum
schedule
01.12.2020
