Merge branch 'master' of github.com:pinterest/pymemcache into switch_to_pytest

Conflicts:
	.gitignore
	tox.ini

.gitignore

@@ -35,3 +35,4 @@ pip-log.txt
 .pypirc
 coverage.xml
 \#*\#
+docs/_build

README.md

@@ -31,7 +31,7 @@ You can also use pip:
 Usage
 =====
 
-See the module documentation in pymemcache.client for details.
+See the documentation here: http://pymemcache.readthedocs.org/en/latest/
 
 Comparison with Other Libraries
 ===============================

docs-requirements.txt

@@ -0,0 +1,3 @@
+sphinx
+sphinx_rtd_theme
+sphinxcontrib-napoleon

docs/apidoc/modules.rst

@@ -0,0 +1,7 @@
+pymemcache
+==========
+
+.. toctree::
+   :maxdepth: 4
+
+   pymemcache

docs/apidoc/pymemcache.rst

@@ -0,0 +1,53 @@
+pymemcache package
+==================
+
+Subpackages
+-----------
+
+.. toctree::
+
+    pymemcache.test
+
+Submodules
+----------
+
+pymemcache.client module
+------------------------
+
+.. automodule:: pymemcache.client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.fallback module
+--------------------------
+
+.. automodule:: pymemcache.fallback
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.pool module
+----------------------
+
+.. automodule:: pymemcache.pool
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.serde module
+-----------------------
+
+.. automodule:: pymemcache.serde
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pymemcache
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/apidoc/pymemcache.test.rst

@@ -0,0 +1,54 @@
+pymemcache.test package
+=======================
+
+Submodules
+----------
+
+pymemcache.test.benchmark module
+--------------------------------
+
+.. automodule:: pymemcache.test.benchmark
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.test.integration module
+----------------------------------
+
+.. automodule:: pymemcache.test.integration
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.test.test_client module
+----------------------------------
+
+.. automodule:: pymemcache.test.test_client
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.test.test_utils module
+---------------------------------
+
+.. automodule:: pymemcache.test.test_utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+pymemcache.test.utils module
+----------------------------
+
+.. automodule:: pymemcache.test.utils
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: pymemcache.test
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/conf.py

@@ -0,0 +1,43 @@
+import os
+
+extensions = [
+    'sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
+    'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinxcontrib.napoleon'
+]
+
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = 'index'
+project = u'pymemcache'
+copyright = u'2015, Pinterest.com'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '1.0.0'
+
+# The full version, including alpha/beta/rc tags.
+release = '1.0.0'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = []
+
+pygments_style = 'sphinx'
+# on_rtd is whether we are on readthedocs.org, this line of code grabbed from
+# docs.readthedocs.org
+on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+if not on_rtd:  # only import and set the theme if we're building docs locally
+    import sphinx_rtd_theme
+    html_theme = 'sphinx_rtd_theme'
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+# otherwise, readthedocs.org uses their theme by default, so no need to specify
+
+html_static_path = ['_static']
+htmlhelp_basename = 'pymemcachedoc'
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}

docs/getting_started.rst

@@ -0,0 +1,58 @@
+Getting started!
+================
+A comprehensive, fast, pure-Python memcached client library.
+
+Basic Usage
+------------
+
+.. code-block:: python
+
+    from pymemcache.client import Client
+
+    client = Client(('localhost', 11211))
+    client.set('some_key', 'some_value')
+    result = client.get('some_key')
+
+
+Serialization
+--------------
+
+.. code-block:: python
+
+     import json
+     from pymemcache.client import Client
+
+     def json_serializer(key, value):
+         if type(value) == str:
+             return value, 1
+         return json.dumps(value), 2
+
+    def json_deserializer(key, value, flags):
+        if flags == 1:
+            return value
+        if flags == 2:
+            return json.loads(value)
+        raise Exception("Unknown serialization format")
+
+    client = Client(('localhost', 11211), serializer=json_serializer,
+                    deserializer=json_deserializer)
+    client.set('key', {'a':'b', 'c':'d'})
+    result = client.get('key')
+
+
+Best Practices
+---------------
+
+ - Always set the connect_timeout and timeout arguments in the constructor to
+   avoid blocking your process when memcached is slow.
+ - Use the "noreply" flag for a significant performance boost. The "noreply"
+   flag is enabled by default for "set", "add", "replace", "append", "prepend",
+   and "delete". It is disabled by default for "cas", "incr" and "decr". It
+   obviously doesn't apply to any get calls.
+ - Use get_many and gets_many whenever possible, as they result in less
+   round trip times for fetching multiple keys.
+ - Use the "ignore_exc" flag to treat memcache/network errors as cache misses
+   on calls to the get* methods. This prevents failures in memcache, or network
+   errors, from killing your web requests. Do not use this flag if you need to
+   know about errors from memcache, and make sure you have some other way to
+   detect memcache server failures.

docs/index.rst

@@ -0,0 +1,17 @@
+Welcome to pymemcached documentation!
+=====================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+   Getting Started </getting_started>
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

pymemcache/client.py

@@ -12,61 +12,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""
-A comprehensive, fast, pure-Python memcached client library.
-
-Basic Usage:
-------------
-
- from pymemcache.client import Client
-
- client = Client(('localhost', 11211))
- client.set('some_key', 'some_value')
- result = client.get('some_key')
-
-
-Serialization:
---------------
-
- import json
- from pymemcache.client import Client
-
- def json_serializer(key, value):
-     if type(value) == str:
-         return value, 1
-     return json.dumps(value), 2
-
- def json_deserializer(key, value, flags):
-     if flags == 1:
-         return value
-     if flags == 2:
-         return json.loads(value)
-     raise Exception("Unknown serialization format")
-
- client = Client(('localhost', 11211), serializer=json_serializer,
-                 deserializer=json_deserializer)
- client.set('key', {'a':'b', 'c':'d'})
- result = client.get('key')
-
-
-Best Practices:
----------------
-
- - Always set the connect_timeout and timeout arguments in the constructor to
-   avoid blocking your process when memcached is slow.
- - Use the "noreply" flag for a significant performance boost. The "noreply"
-   flag is enabled by default for "set", "add", "replace", "append", "prepend",
-   and "delete". It is disabled by default for "cas", "incr" and "decr". It
-   obviously doesn't apply to any get calls.
- - Use get_many and gets_many whenever possible, as they result in less
-   round trip times for fetching multiple keys.
- - Use the "ignore_exc" flag to treat memcache/network errors as cache misses
-   on calls to the get* methods. This prevents failures in memcache, or network
-   errors, from killing your web requests. Do not use this flag if you need to
-   know about errors from memcache, and make sure you have some other way to
-   detect memcache server failures.
-"""
-
 __author__ = "Charles Gordon"
 
 import errno
@@ -175,7 +120,7 @@ class Client(object):
     """
     A client for a single memcached server.
 
-    Keys and Values:
+    Keys and Values
     ----------------
 
      Keys must have a __str__() method which should return a str with no more
@@ -194,7 +139,7 @@ class Client(object):
      already implemented serializers, including one that is compatible with
      the python-memcache library.
 
-    Serialization and Deserialization:
+    Serialization and Deserialization
     ----------------------------------
 
      The constructor takes two optional functions, one for "serialization" of
@@ -206,6 +151,8 @@ class Client(object):
 
      Here is an example using JSON for non-str values:
 
+     .. code-block:: python
+
          def serialize_json(key, value):
              if type(value) == str:
                  return value, 1
@@ -214,11 +161,13 @@ class Client(object):
          def deserialize_json(key, value, flags):
              if flags == 1:
                  return value
+
              if flags == 2:
                  return json.loads(value)
+
              raise Exception("Unknown flags for value: {1}".format(flags))
 
-    Error Handling:
+    Error Handling
     ---------------
 
      All of the methods in this class that talk to memcached can throw one of

tox.ini

@@ -1,8 +1,14 @@
 [tox]
-envlist = py26, py27, pypy, py33, py34
+envlist = py26, py27, pypy, py33, py34, docs
 
 [testenv]
 commands =
     pip install -r test-requirements.txt
     pip install -e .
     py.test {posargs}
+
+[testenv:docs]
+commands =
+    pip install -r docs-requirements.txt
+    sphinx-apidoc -o docs/apidoc/ pymemcache
+    sphinx-build -b html docs/ docs/_build