Creating an info manual by conversion, example for Python ¶

(Date: 28 November 2024)

Summary ¶

I explain how to enable the ability to look up symbols in the documentation for Python by creating a manual in the info format.

Introduction ¶

The ‘lookup symbol’ facility, that you can call from C-h S, also accessible through M-x info-lookup-symbol is very useful (See Prior article). However it depends on a manual being available for the major mode. What if there is no available manual? Here I give an example of how to create a manual by conversion, in the case of Python.

Sphinx ¶

We are using the Sphinx documentation tool. It is licensed under the 2-clause BSD (FreeBSD) LICENSE. This is a free software license compatible with the GPL (See GPL compatible, BSD-2-Clause-FreeBSD.

The key is that Sphinx is able to export to Texinfo (see builders)

Creating the manual on GNU/Linux ¶

The commands applicable for a Debian GNU/Linux System are below, and presumably apply for derivatives such as Ubuntu and Trisquel, with little changes.

Install the package

sudo apt-get install python3-sphinx

Download the relevant documentation for your Python version

$ python --version
Python 3.12.4
$ cd ~/src/python/
$ wget https://www.python.org/ftp/python/3.12.4/Python-3.12.4.tar.xz
$ tar -xf Python-3.12.4.tar.xz
$ cd Python-3-12.4

This is the key step to convert the documentation to Texinfo, and a Makefile for further step below

$ cd Doc
$ sphinx-build -b texinfo -d build/doctrees . build/texinfo
$ cd build/texinfo/

Now convert to info with

$ make

Examine the result

$ ls
Makefile  python-figures  python.info  python.texi

Now you can test the info manual, with the prefix argument to info which allows you to specify an info file C-u C-h i python.info

You can add info manuals in a personal folder

(add-to-list 'Info-additional-directory-list "/home/user1/info")

Now copy the output files, remove any earlier manual, and install the manual into the special ‘dir’ structure. (See Manual).

$ cp -r python-figures python.info ~/info/
$ install-info --delete python.info --dir-file=/home/user1/info/dir
$ install-info --add-once python.info --section=Python
--description="Python manual 3.12.4" --dir-file=/home/user1/info/dir

Setting up C-h S ¶

In order to tell Emacs which manual to use to look up a symbol, you can use the following. The part of Emacs that handles this is the built-in package info-look, see C-h P info-look.

Here we add an entry for the basic Python mode, and also the Python ‘tree-sitter’ mode. (See tree-sitter)

Insert this Lisp code in your init file.

(require 'info-look)

(info-lookup-maybe-add-help
 :mode 'python-mode
 :regexp "[[:alnum:]_]+"
 :doc-spec
 '(("(python)Index" nil "")))

(info-lookup-maybe-add-help
 :mode 'python-ts-mode
 :regexp "[[:alnum:]_]+"
 :doc-spec
 '(("(python)Index" nil "")))

Using the new manual ¶

Finally, you can test if C-h S works by opening a Python file.

Conclusion ¶

Converting an existing manual into the info format for use with C-h S is fairly straightforward, and useful.