如何获取Python文档的Texinfo Info格式?
自从Python 2.6开始,文档似乎采用了新的reStructuredText格式,这让直接生成Texinfo Info文件变得不太容易了。
我非常喜欢使用Emacs,喜欢把文档安装在Info格式里。
有没有人有Python 2.6或更高版本的文档是Texinfo格式的?你们是怎么转换的?或者有没有哪个地方有维护好的版本?
我知道可以用w3m或者haddoc来查看HTML文档,但我真的想要的是Info格式的。
我试过Pandoc,但是经过几次小实验后发现,它对文档之间的链接处理得不太好。而我做的一个大实验是把所有文档合在一起看看会发生什么,结果到现在已经两天了,它还在忙着处理!
两个不错的答案
下面我想强调两个答案,因为SO不允许我同时接受两个答案:
10 个回答
毫无疑问,自己生成特定版本的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是上面树状结构中的一个文件名(第四个),你甚至可以为一些常用的节点添加书签,以便于日常查看。
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
。
如果你在用Emacs编辑器,并且已经添加了MELPA这个软件源,你只需要输入 M-x package-install python-info
就可以轻松安装它。