README for pydoc-info

pydoc-info is an Emacs package for searching and browsing the new Python documentation in the Info browser.

Features

Improved Info-lookup support:

Allows you to quickly find the relevant documentation using the standard command info-lookup-symbol (C-h S).

Hide superfluous *note: references:

Prevent Info from displaying *note: or see in front of cross-references when browsing the Python documentation. This does not affect other Info documents.

Python Info Documents

This package is designed to work with Info files produced from the "new" Python documentation. The "new" documentation is used to distinguish the current documents written in RestructedText and built using Sphinx to the older versions written in Latex (circa python 2.4).

Support for generating the necessary Info files is currently limited to the development branch of Sphinx. Thus they are not yet available at the Python download site nor can they built from source without making a few modifications.

Setup and Install

Before using this package, you may need to download and install the necessary Info files:

wget https://bitbucket.org/jonwaltman/pydoc-info/downloads/python.info.gz
gunzip python.info
sudo cp python.info /usr/share/info
sudo install-info --info-dir=/usr/share/info python.info

Then add the following to your ~/.emacs.d/init.el:

(add-to-list 'load-path "~/path/to/pydoc-info")
(require 'pydoc-info)

Using Info-lookup with other Sphinx-based Documents

The Info-lookup support provided by this package is not limited to the standard Python documentation. It can easily be extended to work with other Sphinx-based documents that have been compiled to Info files.

For example, the documentation for the development version of Sphinx can be compiled to the Info file "sphinx.info". By adding the following code to your .emacs, you can enable info-lookup-symbol to work for both the standard Python modules and Sphinx:

(info-lookup-add-help
 :mode 'python-mode
 :parse-rule 'pydoc-info-python-symbol-at-point
 :doc-spec
 '(("(python)Index" pydoc-info-lookup-transform-entry)
   ("(sphinx)Index" pydoc-info-lookup-transform-entry)))

Building the Python Documentation

If you want to build the Python documentation yourself, follow these steps:

1. Download and install the development version of Sphinx (virtualenv may be useful):

   hg clone https://bitbucket.org/jonwaltman/sphinx-info
   cd sphinx-info
   sudo python setup.py install
   

2. Install some libraries:

   pip install docutils jinja2 pygments
   

3. Download the Python source:

   wget http://www.python.org/ftp/python/2.7.1/Python-2.7.1.tar.bz2
   tar xf Python-2.7.1.tar.bz2
   

4. Modify the configuration file conf.py:

   cd Python-2.7.1/Doc
   cat >> conf.py
   
   texinfo_documents = [
       ('contents', 'python', 'Python Documentation', _stdauthor,
        'Python', 'The Python Documentation', 'Software Development'),
   ]
   

5. Generate the Texinfo:

   mkdir -p build/texinfo build/doctrees
   sphinx-build -b texinfo -d build/doctrees . build/texinfo
   

6. Build the Info files:

   cd build/texinfo
   makeinfo --no-split python.texi
   

7. Install the Info file (optional):

   sudo cp python.info /usr/share/info
   sudo install-info --info-dir=/usr/share/info python.info
   

Links

https://bitbucket.org/jonwaltman/pydoc-info

pydoc-info Mercurial repository

https://bitbucket.org/birkenfeld/sphinx/

Main Sphinx devolopment repository

https://bitbucket.org/jonwaltman/sphinx-info/

Fork of the main Sphinx repository for development on the Texinfo builder

Notes

pydoc-info is hosted and developed on Bitbucket https://bitbucket.org/jonwaltman/pydoc-info/.

Any problems, suggestions, criticisms, or comments can be reported on Bitbucket or sent to [email protected].

Copyright (C) 2011, and GNU GPL'd, by Jonathan Waltman.