4a9188e89cfd — Jon Waltman 10 years ago
Add more commentary in pydoc-info.el
1 files changed, 68 insertions(+), 19 deletions(-)

M pydoc-info.el
M pydoc-info.el +68 -19
@@ 21,27 21,71 @@ 
 ;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
 ;;; Commentary:
-;; This package provides routines to better search and browse the
-;; Python documentation in Info.
-;;; Features:
-;; - 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.
-;;; Install:
-;; 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:
+;; Features:
+;; - 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
+;;   library.
-;; https://bitbucket.org/jonwaltman/pydoc-info/downloads/python.info.gz
+;; - 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
+;;   `pydoc-info-hide-note-references'.
+;; Installation:
-;; 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)
-;;; Usage:
-;;   C-h S : info-lookup-symbol
+;; Extending:
+;; 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"))
+;; Notes:
+;; 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
+;; versions.
+;; Please email bug reports and suggestions to the author, or submit
+;; them at https://bitbucket.org/jonwaltman/pydoc-info/issues
 ;;; Code:

@@ 49,16 93,19 @@ 
 (require 'info-look)
 (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'."
   :group 'pydoc-info)
 ;; Is there a better way to do this?
 (defadvice info-insert-file-contents (after
-                                      pydoc-info-info-insert-file-contents
+                                      pydoc-info-after-insert-file-contents
   "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 
 (pydoc-info-add-help '("python"))
+(defvar python-dotty-syntax-table)
 (defun pydoc-info-python-symbol-at-point ()
   "Return the current Python symbol."
   (require 'python)