Как получить документацию по Python в формате Texinfo Info?
Начиная с Python 2.6, кажется, что документация находится в новом формате reStructuredText, и кажется, что создать Texinfo Info из коробки уже не очень легко.
Я наркоман Emacs и предпочитаю, чтобы моя документация была установлена в Info.
У кого-нибудь есть документы Python 2.6 или новее в формате Texinfo? Как вы их конвертировали? Или есть где-то поддерживаемая сборка?
Я знаю, что могу использовать w3m или haddoc для просмотра html-документов - я действительно хочу их в Info.
Я играл с Pandoc, но после нескольких небольших экспериментов он, кажется, не очень хорошо справляется со связями между документами, и мой более крупный эксперимент - проведение его по всем документам, собранным вместе, чтобы увидеть, что происходит, - все еще пыхтит два дня с тех пор как я начал это!
Два хороших ответа
Выделение двух ответов ниже, потому что ТАК не позволит мне принять оба ответа:
- @ wilfred-hughes: установка из MELPA - это самый быстрый способ получить информацию о предварительной сборке в Emacs
- @alioth: Построить его самому, похоже, намного проще, чем когда я задавал этот вопрос в 2009 году.
10 ответов
Я упаковал документы по Python в виде файла texinfo.
Если вы используете Emacs с MELPA, вы можете просто установить его с M-x package-install python-info,
Джон Уолтман (Jon Waltman) http://bitbucket.org/jonwaltman/sphinx-info разветвил sphinx и написал сборщик texinfo, он может создавать документацию по python (я еще этого не сделал). Похоже, скоро он будет объединен в сфинкса.
Вот быстрые ссылки для загрузки (временные):
Шаги для создания документа Python в формате texinfo:
Загрузите исходный код Python
Загрузите и установите пакет sphinx-info (в virtualenv)
Войдите в каталог Python/Doc из источников Python
Отредактируйте Makefile, чтобы build цель заменить $(PYTHON) tools/sphinx-build.py с sphinx-build, затем добавьте эту цель в make-файл, обратите внимание, пробел перед echo является TAB:
texinfo: BUILDER = texinfo
texinfo: build
@echo
@echo "Build finished. The Texinfo files are in _build/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
Отредактируйте Python/Doc/conf.py, добавив:
texinfo_documents = [
('contents', 'python', 'Python Documentation', 'Georg Brandl',
'Python', 'The Python Programming Language', 'Documentation tools',
1),
]
Тогда беги make texinfo и он должен создать текстовый файл в каталоге build / texinfo. Для генерации информационного файла запустите makeinfo python.texi
Без сомнения, было бы здорово и сложно создать документацию по Python для вашей конкретной версии Python. Просто следуйте EmacsWiki или не стесняйтесь компилировать его локально (в Debian Jessy для Python3.4.2):
sudo apt-get install python3-sphinx
cd ~/Desktop
wget https://www.python.org/ftp/python/3.4.2/Python-3.4.2rc1.tar.xz
tar -xf Python-3.4.2rc1.tar.xz
cd Python-3.4.2rc1/Doc/
sphinx-build -b texinfo -d build/doctrees . build/texinfo
# extra time to build
cd build/texinfo/
makeinfo python.texi
# extra time for convertation
Я получил это дерево:
.
├── logging_flow.png
├── Makefile
├── pathlib-inheritance.png
├── python.info
├── python.info-1
├── python.info-10
├── python.info-11
├── python.info-12
├── python.info-13
├── python.info-14
├── python.info-15
├── python.info-16
├── python.info-17
├── python.info-18
├── python.info-19
├── python.info-2
├── python.info-20
├── python.info-21
├── python.info-22
├── python.info-23
├── python.info-24
├── python.info-25
├── python.info-26
├── python.info-27
├── python.info-28
├── python.info-29
├── python.info-3
├── python.info-30
├── python.info-31
├── python.info-32
├── python.info-33
├── python.info-34
├── python.info-4
├── python.info-5
├── python.info-6
├── python.info-7
├── python.info-8
├── python.info-9
├── python.texi
├── python-video-icon.png
├── tulip_coro.png
└── turtle-star.png
И теперь можно просматривать нативную документацию по Python в Emacs:
Cu Ch i python-info RET
python-info - это имя файла (четвертое в дереве выше), и даже для закладки некоторых произвольных узлов для удобства обычного и регулярного просмотра.
Для тех, кто следит за этим вопросом в надежде получить ответ, я нашел другую реализацию rst2texinfo, которую вы можете попробовать:
Еще один "обходной путь" - выполнить pydoc как предлагает Никокрок прямо в Emacs:
(defun pydoc (&optional arg)
(interactive)
(when (not (stringp arg))
(setq arg (thing-at-point 'word)))
(setq cmd (concat "pydoc " arg))
(ad-activate-regexp "auto-compile-yes-or-no-p-always-yes")
(shell-command cmd)
(setq pydoc-buf (get-buffer "*Shell Command Output*"))
(switch-to-buffer-other-window pydoc-buf)
(python-mode)
(ad-deactivate-regexp "auto-compile-yes-or-no-p-always-yes")
)
Майкл Эрнст (Michael Ernst) поддерживал форматы информации в документах Python:
http://www.cs.washington.edu/homes/mernst/software/
Вы можете попробовать использовать его makefile и скрипт html2texi для генерации обновленной версии. Оба связаны по вышеуказанному URL. Я не уверен, насколько хорошо он работает сейчас (последняя версия была около 2001 года), но его сценарий хорошо прокомментирован (grep для "python").
Вы не поверите, но проект 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/ и загрузите архив для своей версии 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...
... самый ленивый способ
Открыть
python.info файл и включить
M-x Info-mode.
... путем создания узла в файле каталога вручную
Проверьте
C-h v Info-default-directory-listгде хранятся информационные файлы. Положите
python.infoфайл там. В этом каталоге также будет файл с именем
dir. Это
texinfoсгенерированный файл, содержащий список узлов. Вы можете отредактировать его вручную, чтобы включить информацию о Python. Просто добавьте запись ниже
* Menu::
* Menu:
Python
* Python: (python). Python Documentation
... строго используя
texinfo
Для получения полной информации о том, как восстановить список узлов с помощью
texinfoсистему см. https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Installing-an-Info-File.html.
Документы Python теперь генерируются с использованием фреймворка Sphynx. Эта структура не имеет выходного формата texinfo. В настоящее время оно имеет:
- HTML
- латекс
- простой текст
Может быть, вы можете получить то, что вы хотите, используя выход латекса. С выводом текста вы потеряете перекрестный реф.
Лично я предпочитаю использовать pydoc, когда я хочу текстовый вывод. С Vim у меня есть ярлык для вызова pydoc и открыть окно с документом для объекта под моим курсором...
Для Python 3.8.0 и более поздних версий предварительно созданные файлы Info доступны по адресу https://www.python.org/ftp/python/doc и / или https://docs.python.org/3/archives/ .
Дистрибутив Ubuntu предоставляет пакеты pythonX.Y-doc (которые включают документацию в формате Info) как минимум с 18.04 (бионический); в 19.04 XY обозначает 2.7, 3.7 и 3.8. У пакета не так много зависимостей, я предполагаю, что его можно установить и в других дистрибутивах.