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

34 投票
10 回答
6177 浏览
提问于 2025-04-15 12:32

自从Python 2.6开始,文档似乎采用了新的reStructuredText格式,这让直接生成Texinfo Info文件变得不太容易了。

我非常喜欢使用Emacs,喜欢把文档安装在Info格式里。

有没有人有Python 2.6或更高版本的文档是Texinfo格式的?你们是怎么转换的?或者有没有哪个地方有维护好的版本?

我知道可以用w3m或者haddoc来查看HTML文档,但我真的想要的是Info格式的。

我试过Pandoc,但是经过几次小实验后发现,它对文档之间的链接处理得不太好。而我做的一个大实验是把所有文档合在一起看看会发生什么,结果到现在已经两天了,它还在忙着处理!

两个不错的答案

下面我想强调两个答案,因为SO不允许我同时接受两个答案:

  • @wilfred-hughes: 从MELPA安装是把预构建的文档快速放进Emacs的最佳方法
  • @alioth: 自己构建看起来比我在2009年问这个问题时简单多了

10 个回答

5

毫无疑问,自己生成特定版本的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

现在可以在Emacs中原生查看Python文档了,方法是:

C-u C-h i python-info RET

这里的python-info是上面树状结构中的一个文件名(第四个),你甚至可以为一些常用的节点添加书签,以便于日常查看。

24

Jon Waltman http://bitbucket.org/jonwaltman/sphinx-info 对sphinx进行了修改,并写了一个texinfo构建工具,这个工具可以生成Python的文档(我还没试过)。看起来这个工具很快就会和sphinx合并在一起。

这里有一些临时的下载链接:

生成Python文档为texinfo格式的步骤:

首先下载Python的源代码。

然后下载并安装sphinx-info这个包(在一个虚拟环境中)。

接着进入Python源代码中的Python/Doc目录。

编辑Makefile文件,把build目标中的$(PYTHON) tools/sphinx-build.py替换成sphinx-build,然后在Makefile中添加这个目标,注意,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目录下生成texifile。要生成info文件,运行makeinfo python.texi

10

我把Python文档打包成了一个texinfo文件

如果你在用Emacs编辑器,并且已经添加了MELPA这个软件源,你只需要输入 M-x package-install python-info 就可以轻松安装它。

撰写回答