How do you get Python documentation in Texinfo Info format?

Question

Since Python 2.6, it seems the documentation is in the new reStructuredText format, and it doesn\'t seem very easy to build a Texinfo Info file out of the box anymore.

I

Answer 1

For Python 3.8.0 and later, pre-built Info files are available at https://www.python.org/ftp/python/doc and/or https://docs.python.org/3/archives/.

Answer 2

Python docs are now generated using Sphynx framework. This framework does not have texinfo output format. Currently it has:

1. HTML
2. latex
3. plain text

Maybe you can get what you want using the Latex output. With the text output you will lost the cross ref.

Personnaly I prefer using pydoc when I want textual output. With Vim I have a shorcut to call pydoc and open a window with the doc for the entity under my cursor...

Answer 3

Believe it or not, the Python project actually provides us a way to do this through various Makefiles. The files utilize the Python Sphinx project to generate a texi file which makeinfo can then convert to info, the format Emacs uses for documentation.

In addition to Python3000, these instructions require GNU Make and Texinfo. These are packaged in most Linux distributions. Different distros may use different naming conventions. Refer to your distro's documentation for the corresponding package names. For Debian based distros:

# 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

Package names are usually similar for non-Debian systems. For Windows users, I recommend WSL or creating a virtual machine.

1. Download the documentation

Navigate to https://www.python.org/ftp/python/ and download the tarball for your Python version. It will look like:

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

You can use wget to download the tarball and tar to unpack it. The options x and f are for "extract file":

# 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. Run make venv in Python-X.Y.Z/Doc

Sphinx requires more dependencies than are bundled with the basic pip install. Fortunately, the Python project provides a Makefile to create the necessary environment. See the Makefile for precise details.

# 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. Run sphinx-build

Now that the correct environment is set up, we can run Sphinx. This call creates a cache used during generation with the -d option. The documentation files found in the current directory are converted by the texinfo "builder" and output to 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. Use makeinfo to generate the info file

Again, the Python maintainers have given us what we need (even if they haven't documented it well). The previous command created a texi file along with another Makefile. The Makefile calls 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

Like Indiana Jones, you behold the Holy Grail. Many have perished in this journey; you have prevailed. Take a moment to celebrate.

Note: The makeinfo conversion yields errors for me. No matter, I say. The desired info is obtained and I greedily drink from it.

5. Load python.info into Emacs...

Check C-h v Info-default-directory-list for where info files are stored. Put the python.info file there. In that directory should also be a file called dir (if it's not there, don't worry, it will be created). This is a texinfo generated file containing the node listing. While it's possible to edit this manually, doing so is error prone¹.

Run update-info-dir in whichever directory you put python.info to update dir to include the new file.

For complete details about the texinfo system, see https://www.gnu.org/software/texinfo/manual/texinfo/html_node/Installing-an-Info-File.html.

If you're lazy, you could also simply open the python.info file and enable M-x Info-mode.

¹Aside from human error, like mistyping a reference, issues may arise due to "malformed" dir files.

Answer 4

The Ubuntu distribution provides packages pythonX.Y-doc (which include the documentation in Info format) at least since 18.04 (bionic); in 19.04 X.Y stands for 2.7, 3.7 and 3.8. The package does not have many dependencies, I assume it is possible to install it in other distributions too.

Answer 5

With no doubt it would be cool and challenging to generate the Python documentation on your particular Python version by yourself. Just follow EmacsWiki, or feel free to compile it locally (at 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

I got this tree:

.                                                                                                                              
├── 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

And now it is possible to review python documentation natively in Emacs by

C-u C-h i python-info RET

python-info is a filename (fourth in the tree above), and even to bookmark some arbitrary nodes for habitual and regular reviewing convenience.

Answer 6

I've packaged up the Python docs as a texinfo file.

If you're using Emacs with MELPA, you can simply install this with M-x package-install python-info.