1. Jon Waltman
  2. pydoc-info


pydoc-info /

Filename Size Date modified Message
44 B
Add a Makefile
494 B
Add a Makefile
4.2 KB
Update regexps due to changes in how Sphinx formats indexes
85 B
Add ELPA support
7.9 KB
Add more commentary in pydoc-info.el
..              -*- restructuredtext -*-

 README for pydoc-info

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


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::

   :mode 'python-mode
   :parse-rule 'pydoc-info-python-symbol-at-point
   '(("(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:

#. 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

#. Install some libraries::

      pip install docutils jinja2 pygments

#. 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

#. 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'),

#. Generate the Texinfo::

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

#. Build the Info files::

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

#. Install the Info file (optional)::

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


  pydoc-info Mercurial repository

  Main Sphinx devolopment repository

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


pydoc-info is hosted and developed on Bitbucket

Any problems, suggestions, criticisms, or comments can be reported on
Bitbucket or sent to jonathan.waltman@gmail.com.

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