From f4519f3b7f1f7314b5d342be989df1c4365954b9 Mon Sep 17 00:00:00 2001 From: Chayim Date: Thu, 25 Nov 2021 16:03:30 +0200 Subject: Splitting documentation for read the docs (#1743) --- docs/backoff.rst | 5 +++ docs/conf.py | 22 ++++++++++--- docs/connections.rst | 12 +++++++ docs/exceptions.rst | 7 ++++ docs/genindex.rst | 2 ++ docs/index.rst | 78 +++++++++++++++++++++++++++++++------------- docs/lock.rst | 5 +++ docs/redis_core_commands.rst | 14 ++++++++ docs/redismodules.rst | 19 +++++++++++ docs/requirements.txt | 1 + docs/retry.rst | 5 +++ docs/sentinel_commands.rst | 20 ++++++++++++ 12 files changed, 163 insertions(+), 27 deletions(-) create mode 100644 docs/backoff.rst create mode 100644 docs/connections.rst create mode 100644 docs/exceptions.rst create mode 100644 docs/genindex.rst create mode 100644 docs/lock.rst create mode 100644 docs/redis_core_commands.rst create mode 100644 docs/redismodules.rst create mode 100644 docs/retry.rst create mode 100644 docs/sentinel_commands.rst (limited to 'docs') diff --git a/docs/backoff.rst b/docs/backoff.rst new file mode 100644 index 0000000..e640b56 --- /dev/null +++ b/docs/backoff.rst @@ -0,0 +1,5 @@ +Backoff +############# + +.. automodule:: redis.backoff + :members: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index f497e3d..8520969 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -29,7 +29,8 @@ sys.path.append(os.path.abspath(os.path.pardir)) extensions = [ "sphinx.ext.autodoc", "sphinx.ext.doctest", - "sphinx.ext.viewcode" + "sphinx.ext.viewcode", + "sphinx.ext.autosectionlabel", ] # Add any paths that contain templates here, relative to this directory. @@ -53,10 +54,11 @@ copyright = "2021, Redis Inc" # built documents. # # The short X.Y version. -version = "4.0" +import redis +version = '.'.join(redis.__version__.split(".")[0:2]) # The full version, including alpha/beta/rc tags. -release = "4.0.0" +release = redis.__version__ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. @@ -93,17 +95,27 @@ pygments_style = "sphinx" # A list of ignored prefixes for module index sorting. # modindex_common_prefix = [] +nitpicky = True + # -- Options for HTML output -------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "default" +html_theme = "sphinx_rtd_theme" # 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 # documentation. -# html_theme_options = {} +html_theme_options = { + 'display_version': True, + 'prev_next_buttons_location': 'bottom', + 'style_external_links': False, + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, +} # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/docs/connections.rst b/docs/connections.rst new file mode 100644 index 0000000..973821b --- /dev/null +++ b/docs/connections.rst @@ -0,0 +1,12 @@ +Connecting to Redis +##################### + +Generic Client +************** +.. autoclass:: redis.client.Redis + :members: + +Connection Pools +***************** +.. autoclass:: redis.connection.ConnectionPool + :members: \ No newline at end of file diff --git a/docs/exceptions.rst b/docs/exceptions.rst new file mode 100644 index 0000000..b8aeb33 --- /dev/null +++ b/docs/exceptions.rst @@ -0,0 +1,7 @@ + + +Exceptions +########## + +.. automodule:: redis.exceptions + :members: \ No newline at end of file diff --git a/docs/genindex.rst b/docs/genindex.rst new file mode 100644 index 0000000..c1f8355 --- /dev/null +++ b/docs/genindex.rst @@ -0,0 +1,2 @@ +Module Index +============ \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index 8af5385..392acad 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,37 +6,71 @@ Welcome to redis-py's documentation! ==================================== -Indices and tables ------------------- +Getting Started +**************** -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +`redis-py `_ requires a running Redis server, and Python 3.6+. See the `Redis +quickstart `_ for Redis installation instructions. -Contents: ---------- +redis-py can be installed using pip via ``pip install redis``. + + +Quickly connecting to redis +************ + +There are two quick ways to connect to Redis. + +Assuming you run Redis on localhost:6379 (the default):: + import redis + r = redis.Redis() + r.ping() + +Running redis on foo.bar.com, port 12345:: + import redis + r = redis.Redis(host='foo.bar.com', port=12345) + r.ping() + +Another example with foo.bar.com, port 12345:: + import redis + r = redis.from_url('redis://foo.bar.com:12345') + r.ping() + +After that, you probably want to `run redis commands `_. .. toctree:: - :maxdepth: 2 + :hidden: + + genindex -.. automodule:: redis - :members: +Redis Command Functions +*********************** +.. toctree:: + :maxdepth: 2 -.. automodule:: redis.backoff - :members: + redis_core_commands + sentinel_commands + redismodules -.. automodule:: redis.connection - :members: +Module Documentation +******************** +.. toctree:: + :maxdepth: 1 -.. automodule:: redis.commands - :members: + backoff + connections + exceptions + lock + retry -.. automodule:: redis.exceptions - :members: +Contributing +************* -.. automodule:: redis.lock - :members: +- `How to contribute `_ +- `Issue Tracker `_ +- `Source Code `_ +- `Release History `_ -.. automodule:: redis.sentinel - :members: +License +******* +This projectis licensed under the `MIT license `_. \ No newline at end of file diff --git a/docs/lock.rst b/docs/lock.rst new file mode 100644 index 0000000..cce0867 --- /dev/null +++ b/docs/lock.rst @@ -0,0 +1,5 @@ +Lock +######### + +.. automodule:: redis.lock + :members: \ No newline at end of file diff --git a/docs/redis_core_commands.rst b/docs/redis_core_commands.rst new file mode 100644 index 0000000..edfd7fe --- /dev/null +++ b/docs/redis_core_commands.rst @@ -0,0 +1,14 @@ +Redis Core Commands +#################### + +The following functions can be used to replicate their equivalent `Redis command `_. Generally they can be used as functions on your redis connection. For the simplest example, see below: + +Getting and settings data in redis:: + + import redis + r = redis.Redis(decode_responses=True) + r.set('mykey', 'thevalueofmykey') + r.get('mykey') + +.. autoclass:: redis.commands.core.CoreCommands + :members: \ No newline at end of file diff --git a/docs/redismodules.rst b/docs/redismodules.rst new file mode 100644 index 0000000..da8c36b --- /dev/null +++ b/docs/redismodules.rst @@ -0,0 +1,19 @@ +Redis Modules Commands +###################### + +Accessing redis module commands requires the installation of the supported `Redis module `_. For a quick start with redis modules, try the `Redismod docker `_. + +RedisTimeSeries Commands +************************ +.. automodule:: redis.commands.timeseries.commands + :members: TimeSeriesCommands + +RedisJSON Commands +****************** +.. automodule:: redis.commands.json.commands + :members: JSONCommands + +RediSearch Commands +******************* +.. automodule:: redis.commands.search.commands + :members: SearchCommands \ No newline at end of file diff --git a/docs/requirements.txt b/docs/requirements.txt index 2e1c4fb..6dc905f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,2 +1,3 @@ sphinx<2 docutils<0.18 +sphinx-rtd-theme diff --git a/docs/retry.rst b/docs/retry.rst new file mode 100644 index 0000000..2b4f22c --- /dev/null +++ b/docs/retry.rst @@ -0,0 +1,5 @@ +Retry Helpers +############# + +.. automodule:: redis.retry + :members: \ No newline at end of file diff --git a/docs/sentinel_commands.rst b/docs/sentinel_commands.rst new file mode 100644 index 0000000..e5be11e --- /dev/null +++ b/docs/sentinel_commands.rst @@ -0,0 +1,20 @@ +Redis Sentinel Commands +======================= + +redis-py can be used together with `Redis +Sentinel `_ to discover Redis nodes. You +need to have at least one Sentinel daemon running in order to use +redis-py's Sentinel support. + +Connection example (assumes redis redis on the ports listed below): + + >>> from redis import Sentinel + >>> sentinel = Sentinel([('localhost', 26379)], socket_timeout=0.1) + >>> sentinel.discover_master('mymaster') + ('127.0.0.1', 6379) + >>> sentinel.discover_slaves('mymaster') + [('127.0.0.1', 6380)] + + +.. autoclass:: redis.commands.sentinel.SentinelCommands + :members: \ No newline at end of file -- cgit v1.2.1