@@ 21,27 21,71 @@
;; along with this program. If not, see <http://www.gnu.org/licenses/>.
-;; This package provides routines to better search and browse the
-;; Python documentation in Info.
-;; - Enable `info-lookup-symbol' to work with the new Python docs
-;; - Improve browsing of Python Info docs by hiding *note: references.
+;; pydoc-info provides routines to better search and browse the Python
+;; documentation in Info.
-;; To use this package, you will need to have a recent version of the
-;; Python documentation in the Info format on your machine. It can be
-;; downloaded at:
+;; - Improved Info-lookup support for Python allows quick access to
+;; the documentation using `info-lookup-symbol' (C-h S) with symbol
+;; completion for every Python object documented in the standard
+;; - 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 how other Info
+;; documents are displayed and is controlled by the variable
-;; Then add this file to your load-path and put the following
-;; expression into your ~/.emacs.d/init.el.
+;; Before using this package, you may need to download and install the
+;; latest Python 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)
-;; C-h S : info-lookup-symbol
+;; 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 Python packages that also use Sphinx for
+;; documentation and have generated the necessary Info files.
+;; For example, the documentation for Sphinx can be compiled to the
+;; Info file "sphinx.info" and you have added it to your `INFOPATH'.
+;; By adding the following code to your `init.el', you can use
+;; `info-lookup-symbol' to search the documentation for both Sphinx
+;; and the standard Python modules.
+;; (pydoc-info-add-help '("python" "sphinx"))
+;; pydoc-info is designed to work with Info files produced from the
+;; "new" Python documentation (v2.6 and above). The "new"
+;; documentation is written in ReStructuredText and built using
+;; Sphinx. The previous Python Info files were generated from the old
+;; documentation written in LaTeX.
+;; Texinfo support is a recent addition to Sphinx and is currently
+;; limited to the latest development branch. The Info files
+;; referenced here are not part of the official Python distribution.
+;; The current `info-lookup' support in "python.el" (circa v24.0) is
+;; based on the older Info files and doesn't work with the newer
+;; Please email bug reports and suggestions to the author, or submit
+;; them at https://bitbucket.org/jonwaltman/pydoc-info/issues
@@ 49,16 93,19 @@
(defcustom pydoc-info-hide-note-references t
- "*Non-nil if note references should be hidden in Python Info
+ "Non-nil if note references should be hidden in Python Info
+This variable is used by `pydoc-info-after-insert-file-contents'
+which advises the function `info-insert-file-contents'."
;; Is there a better way to do this?
(defadvice info-insert-file-contents (after
"Hack to make `Info-hide-note-references' buffer-local and
-automatically set to `hide' iff it can be determined that this
+automatically set to `hide' if it can be determined that this
file was created from a Texinfo file generated by Docutils or
@@ 101,6 148,8 @@ MORE-SPECS are additional or overriding
(defun pydoc-info-python-symbol-at-point ()
"Return the current Python symbol."