WhooshDoc
=========
WhooshDoc is an indexed, full-text search tool for Python docstrings. It uses
Whoosh_ to do the indexing and searching, hence the name. It includes tools for
collecting docstrings to index them and for searching the index.
Prerequisites
-------------
For searching a prepared index, all you need is Whoosh_. WhooshDoc uses epydoc_
to traverse packages and collect their docstrings in order to build a search
index. However, epydoc is not required; you can add to a WhooshDoc index using
the Whoosh_ API (see whooshdoc/util.py for the schema), without using epydoc.
This package uses setuptools_ for installation and for locating a default
WhooshDoc index. WhooshDoc uses argparse_ for command line arguments.
Installation
------------
You can install WhooshDoc, along with its dependencies, using with setuptools'
easy_install::
$ easy_install WhooshDoc
or via the normal setup.py mechanism after downloading and unpacking the
tarball::
$ cd WhooshDoc-1.0
$ python setup.py install
To use the wxPython_ search GUI, you must install Enthought's Traits_ and
TraitsBackendWX_ packages. To do this, use the following easy_install command::
$ easy_install 'WhooshDoc[ui]'
The development source may be checked out via Subversion::
$ svn co https://svn.enthought.com/svn/enthought/WhooshDoc/trunk WhooshDoc
wdoc
----
WhooshDoc comes with one script, wdoc. It has several sub-commands. Use
"wdoc --help" and "wdoc <sub-command> --help" to see detailed help.
To index a package using epydoc to collect docstrings, use "wdoc index". For
example::
$ wdoc index numpy
To use the console search utility, use "wdoc search". For example::
$ wdoc search --help # For an explanation of the query syntax.
$ wdoc search bessel or airy not filter
$ wdoc search '"phrase searches need weird quoting"'
# because shells also interpret quote characters.
To use the wxPython_ GUI, use "wdoc ui". For example::
$ wdoc ui
$ wdoc ui bessel or airy not filter
To explicitly specify the WhooshDoc index directory, use the -i/--index option
before any of these sub-commands. For example::
$ wdoc --index ~/Library/WhooshDoc search bessel
To remove certain docstrings (e.g., because you updated a package and want to
reindex it), use "wdoc delgroups". For example::
# First, index a couple of scipy packages with the group name "scipy"
$ wdoc index --group scipy scipy.linalg scipy.optimize
# Now delete them.
$ wdoc delgroups scipy
IPython
-------
WhooshDoc includes an IPython "magic" command, %whoosh, which performs a
WhooshDoc query and presents the results in the console, like the "wdoc search"
command. The %whoosh command integrates with IPython's help mechanisms to
display the help for the individual items. To enable it, add the following to
your `ipy_user_conf.py` file::
from whooshdoc.ipython import enable
enable('/path/to/whooshdoc/index')
Now, you can search using %whoosh in IPython. For example::
In [10]: %whoosh bessel or airy not filter
Bugs
----
Please make a ticket on the Enthought Tool Suite (ETS) Trac instance:
https://svn.enthought.com/enthought
Or send an email to the enthought-dev mailing list:
https://mail.enthought.com/mailman/listinfo/enthought-dev
To Do
-----
* Simple web app using wsgiref.
.. _Whoosh: http://whoosh.ca
.. _epydoc: http://epydoc.sourceforge.net
.. _setuptools: http://pypi.python.org/pypi/setuptools
.. _argparse: http://pypi.python.org/pypi/argparse
.. _wxPython: http://www.wxpython.org
.. _Traits: http://pypi.python.org/pypi/Traits
.. _TraitsBackendWX: http://pypi.python.org/pypi/TraitsBackendWX