Initial implementation of docs

3 files changed, 118 insertions, 0 deletions

diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..76f647a
--- /dev/null
+++ b/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}
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
new file mode 100644
index 0000000..68125fc
--- /dev/null
+++ b/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.
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..bf4f27e
--- /dev/null
+++ b/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`