如何获取 Texinfo Info 格式的 Python 文档？

Question

从 Python 2.6 开始，文档似乎位于新的 reStructuredText 格式，构建一个 Texinfo Info< 似乎不太容易/a> 文件不再是开箱即用的。

我是一名 Emacs 迷，更喜欢将文档安装在 Info.plist 中。

有人有 Texinfo 格式的 Python 2.6 或更高版本的文档吗？ 你是如何转换它们的？ 或者，那里有维护的构建吗？

我知道我可以使用 w3m 或 haddoc 来查看 html 文档 - 我真的希望它们在 Info.plist 中。

我玩过 Pandoc 但经过一些小实验后，它似乎不能很好地处理文档之间的链接，而我的更大的实验 - 在所有文档中运行它，看看会发生什么 - 自从我开始以来两天仍然进展顺利！

两个很好的答案

突出显示下面的两个答案，因为 SO 不允许我接受这两个答案：

• @wilfred-hughes：从 MELPA 安装 是获取 Emacs 预构建信息的最快方法
• @alioth: 自己构建 看起来要容易得多比我2009年问这个问题时还要多

Answer 1

Jon Waltman http://bitbucket.org/jonwaltman/sphinx-info 分叉了 sphinx 并编写了一个texinfo builder，它可以构建python文档（我还没有做过）。 看来很快就会合并到sphinx中了。

以下是下载的快速链接（临时）：

• http://dl.dropbox.com/ u/1276730/python.info
• http://dl.dropbox.com/ u/1276730/python.texi

生成 texinfo 格式的 python 文档的步骤：

下载 python 源代码

下载并安装 sphinx-info 包（在 virtualenv 中）

从 python 源进入 Python/Doc 目录

编辑 Makefile，将 build 目标替换 $(PYTHON ) tools/sphinx-build.py 和 sphinx-build ，然后将此目标添加到 makefile 中，注意，echo 之前的空格是制表符：

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 目录中生成 texifile。
要生成信息文件，请运行 makeinfo python.texi

Answer 2

我已将 Python 文档打包为 texinfo 文件。

如果您将 Emacs 与 MELPA 一起使用，则只需使用 Mx package-install python-info 进行安装即可。

Answer 3

毫无疑问，自己生成有关您的特定 Python 版本的 Python 文档是很酷且具有挑战性的。 只需遵循 EmacsWiki，或者随意在本地编译它（在 Debian Jessy for 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

现在可以通过以下方式在 Emacs 中本地查看 Python 文档：

Cu Chi python-info RET

python-info 是一个文件名（上面树中的第四个），甚至可以为某些任意节点添加书签，以方便习惯和定期查看。

Answer 4

对于那些关注这个问题并希望得到答案的人，我找到了您可能想尝试的另一个 rst2texinfo 实现：

http://bitbucket.org/jonwaltman/rst2texinfo/src

Answer 5

另一个“解决方法”是直接在 Emacs 中按照 Nikokrock 的建议执行 pydoc：

(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")
)

Answer 6

Michael Ernst 曾经维护 Python 文档的 Info 格式：

http:// www.cs.washington.edu/homes/mernst/software/#python-info

您可以尝试使用他的 makefile 和 html2texi 脚本来生成更新版本。 两者均链接至上述 URL。 我不确定它现在的效果如何（最后一个版本是在 2001 年左右），但他的脚本得到了很好的注释（grep 代表“python”）。

Answer 7

对于 Python 3.8.0 及更高版本，可在 https://www. python.org/ftp/python/doc 和/或 https://docs.python .org/3/archives/。

Answer 8

Python 文档现在使用 Sphynx 框架生成。 该框架没有 texinfo 输出格式。 目前它有：

1. HTML
2. Latex
3. 纯文本

也许你可以使用 Latex 输出得到你想要的东西。 使用文本输出，您将丢失交叉引用。

当我需要文本输出时，我个人更喜欢使用 pydoc。 使用 Vim，我有一个快捷方式来调用 pydoc 并打开一个窗口，其中包含光标下实体的文档......

Answer 9

Ubuntu 发行版至少从 18.04 (bionic) 开始提供包 pythonX.Y-doc （其中包括 Info 格式的文档）； 19.04 XY 代表 2.7、3.7 和 3.8。 该软件包没有太多依赖项，我认为也可以将其安装在其他发行版中。

Answer 10

不管你相信与否，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 版本的 tarball。 它看起来像：

https://www.python.org/ftp/python/3.7.9/Python-3.7.9.tar.xz

您可以使用 wget 下载 tarball 并使用 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. 在 Python-XYZ/Doc 中运行 make venv >

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“builder”转换并输出到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 转换对我来说会产生错误。 没关系，我说。 获得了所需的信息，我贪婪地喝了它。

5. 将python.info加载到Emacs中...

使用Cu Ch i直接打开python.info。

要在 Emacs 帮助目录节点中安装信息文件，首先
检查 Ch v Info-default-directory-list 以了解信息文件的存储位置。 将 python.info 文件放在那里。 该目录中可能有一个名为 dir 的文件。 dir 文件由 texinfo 生成，包含节点列表。 如果不存在 dir 文件，请不要担心，这就是我们正在创建的文件。 请注意，不建议手动编辑 dir 文件¹。

运行 update-info-dir 位于您放置 python.info 的目录中。 这将使用 python.info 更新（或创建）dir。

有关 texinfo 系统的完整详细信息，请参阅 https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Installing-an-Info-File.html。

¹除了人为错误（例如错误输入引用）之外，“格式错误”的 dir 文件也可能会出现问题。

Answer 11

从 Emacs 信息浏览器识别的源代码构建：

git clone https://github.com/python/cpython.git
cd cpython
./configure
make
cd Doc
make texinfo
cd build/texinfo
make install-info infodir=/usr/local/share/info