coady avatar coady committed 1e3f896

Documentation update with new theme and versioning.

Comments (0)

Files changed (7)

 client
 ======
 .. automodule:: lupyne.client
+.. note::
+  Caching more client connections than the backed server supports will cause blocking under load.  CherryPy's default `thread pool`_ is 10.
 
 Response
 ---------
 
 Pool
 ---------
+.. versionadded:: 1.1+
 .. autoclass:: Pool
   :show-inheritance:
   :members:
 
 Replicas
 ---------
+.. versionadded:: 1.1+
 .. autoclass:: Replicas
   :show-inheritance:
   :members:
+
+.. _thread pool: http://docs.cherrypy.org/stable/refman/_cpserver.html#cherrypy._cpserver.Server.thread_pool
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'default'
+html_theme = 'nature'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Lupyne's documentation!
+Lupyne's documentation
 ==================================
 
-`Lupyne <https://bitbucket.org/coady/lupyne>`_ provides:
- * high-level Pythonic search `engine <engine.html>`_ interface to `PyLucene <http://lucene.apache.org/pylucene/>`_
- * `RESTful <http://en.wikipedia.org/wiki/Representational_State_Transfer>`_ `JSON <http://json.org/>`_ `CherryPy <http://cherrypy.org/>`_ `server <server.html>`_
- * simple Python `client <client.html>`_ for interacting with the server
+Lupyne_ is:
+ * a high-level Pythonic search `engine <engine.html>`_ library, built on PyLucene_
+ * a RESTful_ JSON_ search `server <server.html>`_, built on CherryPy_
+ * a simple Python `client <client.html>`_ for interacting with the server
 
-Quickstart:
+Quickstart
+^^^^^^^^^^
 
   >>> from lupyne import engine                       # don't forget to call lucene.initVM
   >>> indexer = engine.Indexer()                      # create an in-memory index (no filename supplied)
 
 See more `examples <examples.html>`_
 
-Contents:
+Contents
+^^^^^^^^^^
 
 .. toctree::
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
+
+.. _Lupyne: https://bitbucket.org/coady/lupyne
+.. _PyLucene: http://lucene.apache.org/pylucene/
+.. _RESTful: http://en.wikipedia.org/wiki/Representational_State_Transfer
+.. _JSON: http://json.org/
+.. _CherryPy: http://cherrypy.org
   --real-time           search in real-time without committing
 
 .. automodule:: lupyne.server
+.. note::
+  Lucene doc ids are ephemeral;  only use doc ids across requests for the same index version.
 
 tools
 -----------
-`CherryPy tools <http://docs.cherrypy.org/stable/progguide/extending/customtools.html>`_ enabled by default:  tools.\{json,allow,time,validate\}.on
+`CherryPy tools`_ enabled by default:  tools.\{json,allow,time,validate\}.on
 
 .. autofunction:: json_
 .. autofunction:: allow
   :members:
   :exclude-members: new, sync
 
+  .. versionchanged:: 1.1+
+    automatic synchronization and promotion
+
   .. attribute:: fields
 
     optional field settings will trigger indexer promotion when synchronized hosts are exhausted
 -----------
 .. autofunction:: mount
 .. autofunction:: start
+
+.. _CherryPy tools: http://docs.cherrypy.org/stable/progguide/extending/customtools.html
 """
 Restful json clients.
 
-Use `Resource`_ for a single host.
+Use `Resource`_ for a connection to a single host.
+Use `Pool`_ for persistent thread-safe connections to a single host.
 Use `Resources`_ for multiple hosts with simple partitioning or replication.
 Use `Shards`_ for horizontally partitioning hosts by different keys.
 Use `Replicas`_ in coordination with automatic host synchronization.
 
 WebSearcher exposes resources for an IndexSearcher.
 In addition to search requests, it provides access to term and document information in the index.
-Note Lucene doc ids are ephemeral;  they should only be used across requests for the same index version.
 
  * :meth:`/ <WebSearcher.index>`
  * :meth:`/search <WebSearcher.search>`
 Single documents may be added, deleted, or replaced by a unique indexed field.
 Multiples documents may also be added or deleted by query at once.
 By default changes are not visible until the update resource is called to commit a new index version.
-If a near real-time Indexer is used (an experimental feature in Lucene), then changes are instantly searchable.
-In such cases a commit still hasn't occurred;  the index based :meth:`last-modified header <validate>` shouldn't be used for caching.
+If a near real-time Indexer is used, then changes are instantly searchable.
+In such cases a commit still hasn't occurred, and the index based :meth:`last-modified header <validate>` shouldn't be used for caching.
 
  * :meth:`/ <WebIndexer.index>`
  * :meth:`/search <WebIndexer.search>`
 
 Changes in 1.1+:
 ==================
+ * Engine:
+   
+   - Support for all IndexWriterConfig options
+
  * Server:
    
    - Synchronization of searcher with remote hosts
    - Automatic promotion of searcher to indexer
+
+ * Client:
+   
+   - Resource pooling for single hosts
+   - Replica support with automatic failover
 """
 
 import os
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.