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

Question

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

pythonemacsrestructuredtexttexinfo

34

自 Python 2.6 开始，文档似乎采用了新的 reStructuredText 格式，而且似乎不太容易直接构建 Texinfo Info 文件。

我是 Emacs 狂热者，更喜欢在 Info 中安装我的文档。

有没有人有 Python 2.6 或更新版本的 Texinfo 格式文档？你是如何转换它们的？或者，是否有一个维护的构建版本存在？

我知道我可以使用 w3m 或 haddoc 查看 html 文档，但我真的想要它们在 Info 中。

我尝试过 Pandoc，但在进行了几个小实验后，它似乎不能很好地处理文档之间的链接。而我的大型实验——将所有文档连接在一起运行——至今仍在进行中，两天了也没完成！

两个好答案

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

@wilfred-hughes: 从 MELPA 安装是将预构建信息快速引入 Emacs 的最快方法
@alioth: 自己构建看起来比我在 2009 年提出这个问题时要容易得多

- Matt Curtis

31

“与编程无关”-我想你在开玩笑。我的问题具体是关于在特定环境下练习编程。 - Matt Curtis

1

你的 Pandoc 脚本完成了吗？ - seth

1

嗨seth-从某种意义上说，它确实死了，因为我放弃了。两天时间足够让我决定它不是一个好的选择。我的小文件实验表明它并不完美。我刚刚开始着手rst2info项目 - 如果你（或任何人）能够帮忙，我将它放在这里：http://repo.or.cz/w/rst2info.git - 这将是一场艰苦的战斗，因为我从未写过reStructuredText或Texinfo，而且坦白说，我现在也没有真正学习它（或docutils）的兴趣。 - Matt Curtis

1

我已将Python文档打包为texinfo页面，并在MELPA上发布了一个软件包，以便于安装。请告诉我它对您是否有用。 - Wilfred Hughes

10个回答

10

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

如果你在使用MELPA的Emacs，你可以通过M-x package-install python-info进行安装。

- Wilfred Hughes

1

完美，直到“此文件是故意为空”的描述为止；-) 谢谢Wilfred。 - Matt Curtis

建议：这个能插入到 C-h S 机制中吗？这样会使它变得更加有用！ - Clément

@Clément 嗯，不确定它有多容易。你能否打开一个 GitHub 问题描述一下你想象中的工作方式？ - Wilfred Hughes

我通过在我的.bashrc中执行以下命令来使其工作：export INFOPATH=$HOME/.emacs.d/etc/info/python3:"，然后将python.info复制到该文件夹中。 Emacs将所有这样的目录合并到“Info-default-directories”中。请注意环境变量中的尾随“：”，以避免指定默认目录。我还在该目录中创建了一个“dir”文件，只是指向了Python子模块。不确定是否需要最后一个步骤。 - InHarmsWay

5

毫无疑问，自己生成适用于特定Python版本的Python文档将是很酷且具有挑战性的。只需按照EmacsWiki的指示进行操作，或随意在本地编译（例如针对Python 3.4.2 在Debian Jessy上）：

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文档：

C-u C-h i python-info RET

python-info是一个文件名（在上面的树形结构中排第四），你甚至可以为了方便而收藏一些常用的节点。

- Alioth

太好了，谢谢！看起来自2009年黑暗时代以来他们已经修复了它。考虑到MELPA的流行，我认为Wilfred的答案对更多人有用，所以我会保留那个选项，但如果我可以接受两个答案，我肯定会接受这个答案。我将编辑描述，以便这个答案获得更多的关注。 - Matt Curtis

太好了！我注意到在sphinx-build之后生成了一个Makefile，我们也可以使用它来生成.info文件（make info）并安装info（make install-info）。 - Student222

3

如果您正在关注这个问题并希望获得答案，我找到了另一个rst2texinfo的实现，您可能想要尝试一下：

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

- Matt Curtis

2

另一个“解决办法”是直接在Emacs中执行pydoc，正如Nikokrock所建议的那样：

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

- wr.

谢谢您的建议。这是在Emacs中使用Python的顶级技巧，但并没有回答问题。 - Matt Curtis

2

Michael Ernst曾经维护过Python文档的信息格式：

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

你可以尝试使用他的Makefile和html2texi脚本生成更新版。两者均在上述URL中链接。我不确定它现在的工作效果如何（最后一版大约是2001年），但他的脚本有很好的注释（用grep查找“python”）。

- ars

1

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

- volferine

1

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

HTML
latex
纯文本

也许您可以使用Latex输出来获得所需内容。使用文本输出将会失去交叉引用。

个人而言，当我需要文本输出时，我更喜欢使用pydoc。在Vim中，我有一个快捷键来调用pydoc并打开一个窗口，显示光标下实体的文档...

- Nikokrock

谢谢Nikokrock。我知道Sphinx，原问题链接到它。我已经挖掘了一下，似乎将LaTeX转换为Texinfo并不容易 - Pandoc似乎更有前途。有几个人关注这个问题，但你是迄今为止唯一的回答者 - 我想知道大多数Python-Emacs程序员是否在2.6之后就没有Info了？ - Matt Curtis

这是一个我找到的软件包链接：http://members.inode.at/wjenkner/pari-info/The-tex2texi-conversion-package.html。我可以使用它或Pandoc，或者编写自己的转换器，但我正在寻找一种避免这种情况的方法，因为这会分散我注意力，我实际上想要写的是代码！ :-) - Matt Curtis

最新的Sphinx主干版本（1.1pre）实际上已经具备了Texinfo构建器。 - cschol

1

对于Python 3.8.0及更高版本，可在https://www.python.org/ftp/python/doc和/或https://docs.python.org/3/archives/上获取预构建的Info文件。

- Jonathan Moore

1

信不信由你，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下载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-X.Y.Z/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转换产生了错误。无论如何，我还是取得了所需的info文件并贪婪地从中汲取了知识。

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

使用C-u C-h i直接打开python.info。

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

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

有关texinfo系统的完整详细信息，请参见https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Installing-an-Info-File.html。 ¹除了人为错误（例如引用打错），问题可能会因“格式不正确”的dir文件而出现。

- Lorem Ipsum

感谢@lorem ipsum！我认为这个答案基本相同（尽管有额外的说明）与Alioth的（现在在问题中链接，因为只能接受1个答案） - 让我知道如果我错过了什么？ - Matt Curtis

我会说那很准确 :) - Lorem Ipsum

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- pygabriel · Accepted Answer

Jon Waltman http://bitbucket.org/jonwaltman/sphinx-info forked Sphinx and created a Texinfo builder. This builder can be used to generate Python documentation in the Texinfo format. Although I have not tried it myself, it appears that this will soon be incorporated into Sphinx.

Here are some quick links for the downloads (temporary):

Steps to generate Python documentation in Texinfo format:

1. Download the Python source code.

2. Download and install the sphinx-info package (in a virtualenv).

3. Navigate to the Python/Doc directory within the Python source code.

4. Edit the Makefile by replacing $(PYTHON) tools/sphinx-build.py with sphinx-build in the build target. Then add this target to the Makefile. Note that the space before "echo" must be a TAB character.

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

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

两个好答案

1. 下载文档

2. 在 Python-X.Y.Z/Doc 中运行 make venv

3. 运行 sphinx-build

4. 使用makeinfo生成info文件

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

2. 在 `Python-X.Y.Z/Doc` 中运行 `make venv`

3. 运行 `sphinx-build`

4. 使用`makeinfo`生成`info`文件

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