Splitting documentation for read the docs (#1743)

16 files changed, 209 insertions, 60 deletions

diff --git a/README.md b/README.md
index 6e7d964..d068c68 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ The Python interface to the Redis key-value store.
 [![codecov](https://codecov.io/gh/redis/redis-py/branch/master/graph/badge.svg?token=yenl5fzxxr)](https://codecov.io/gh/redis/redis-py)
 [![Total alerts](https://img.shields.io/lgtm/alerts/g/redis/redis-py.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/redis/redis-py/alerts/)
 
-[Installation](##installation) | [Contributing](##contributing) |  [Getting Started](##getting-started) | [Connecting To Redis](##connecting-to-redis)
+[Installation](#installation) | [Contributing](#contributing) |  [Getting Started](#getting-started) | [Connecting To Redis](#connecting-to-redis)
 
 ---------------------------------------------
 
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 <https://pypi.org/project/redis>`_ requires a running Redis server, and Python 3.6+. See the `Redis
+quickstart <https://redis.io/topics/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 <redis_core_commands.html>`_.
 
 .. 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 <https://github.com/redis/redis-py/blob/master/CONTRIBUTING.md>`_
+- `Issue Tracker <https://github.com/redis/redis-py/issues>`_
+- `Source Code <https://github.com/redis/redis-py/>`_
+- `Release History <https://github.com/redis/redis-py/releases/>`_
 
-.. automodule:: redis.sentinel
-   :members:
+License
+*******
 
+This projectis licensed under the `MIT license <https://github.com/redis/redis-py/blob/master/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 <https://redis.io/commands>`_.  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 <https://docs.redis.com/latest/modules/>`_. For a quick start with redis modules, try the `Redismod docker <https://hub.docker.com/r/redislabs/redismod>`_.
+
+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 <https://redis.io/topics/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
diff --git a/redis/commands/timeseries/commands.py b/redis/commands/timeseries/commands.py
index 3b9ee0f..fcb535b 100644
--- a/redis/commands/timeseries/commands.py
+++ b/redis/commands/timeseries/commands.py
@@ -27,7 +27,7 @@ class TimeSeriesCommands:
         """
         Create a new time-series.
         For more information see
-        `TS.CREATE <https://oss.redis.com/redistimeseries/master/commands/#tscreate>`_.  # noqa
+        `TS.CREATE <https://oss.redis.com/redistimeseries/master/commands/#tscreate>`_.
 
         Args:
 
@@ -60,7 +60,7 @@ class TimeSeriesCommands:
             - 'min': only override if the value is lower than the existing value.
             - 'max': only override if the value is higher than the existing value.
             When this is not set, the server-wide default will be used.
-        """
+        """  # noqa
         retention_msecs = kwargs.get("retention_msecs", None)
         uncompressed = kwargs.get("uncompressed", False)
         labels = kwargs.get("labels", {})
@@ -79,10 +79,10 @@ class TimeSeriesCommands:
         """
         Update the retention, labels of an existing key.
         For more information see
-        `TS.ALTER <https://oss.redis.com/redistimeseries/master/commands/#tsalter>`_.  # noqa
+        `TS.ALTER <https://oss.redis.com/redistimeseries/master/commands/#tsalter>`_.
 
         The parameters are the same as TS.CREATE.
-        """
+        """  # noqa
         retention_msecs = kwargs.get("retention_msecs", None)
         labels = kwargs.get("labels", {})
         duplicate_policy = kwargs.get("duplicate_policy", None)
@@ -97,7 +97,7 @@ class TimeSeriesCommands:
         """
         Append (or create and append) a new sample to the series.
         For more information see
-        `TS.ADD <https://oss.redis.com/redistimeseries/master/commands/#tsadd>`_. # noqa
+        `TS.ADD <https://oss.redis.com/redistimeseries/master/commands/#tsadd>`_.
 
         Args:
 
@@ -129,7 +129,7 @@ class TimeSeriesCommands:
             - 'min': only override if the value is lower than the existing value.
             - 'max': only override if the value is higher than the existing value.
             When this is not set, the server-wide default will be used.
-        """
+        """  # noqa
         retention_msecs = kwargs.get("retention_msecs", None)
         uncompressed = kwargs.get("uncompressed", False)
         labels = kwargs.get("labels", {})
@@ -151,8 +151,8 @@ class TimeSeriesCommands:
         Expects a list of `tuples` as (`key`,`timestamp`, `value`).
         Return value is an array with timestamps of insertions.
         For more information see
-        `TS.MADD <https://oss.redis.com/redistimeseries/master/commands/#tsmadd>`_. # noqa
-        """
+        `TS.MADD <https://oss.redis.com/redistimeseries/master/commands/#tsmadd>`_.
+        """  # noqa
         params = []
         for ktv in ktv_tuples:
             for item in ktv:
@@ -167,7 +167,7 @@ class TimeSeriesCommands:
         This command can be used as a counter or gauge that automatically gets
         history as a time series.
         For more information see
-        `TS.INCRBY <https://oss.redis.com/redistimeseries/master/commands/#tsincrbytsdecrby>`_. # noqa
+        `TS.INCRBY <https://oss.redis.com/redistimeseries/master/commands/#tsincrbytsdecrby>`_.
 
         Args:
 
@@ -189,7 +189,7 @@ class TimeSeriesCommands:
         chunk_size:
             Each time-series uses chunks of memory of fixed size for time series samples.
             You can alter the default TSDB chunk size by passing the chunk_size argument (in Bytes).
-        """
+        """  # noqa
         timestamp = kwargs.get("timestamp", None)
         retention_msecs = kwargs.get("retention_msecs", None)
         uncompressed = kwargs.get("uncompressed", False)
@@ -211,7 +211,7 @@ class TimeSeriesCommands:
         This command can be used as a counter or gauge that
         automatically gets history as a time series.
         For more information see
-        `TS.DECRBY <https://oss.redis.com/redistimeseries/master/commands/#tsincrbytsdecrby>`_. # noqa
+        `TS.DECRBY <https://oss.redis.com/redistimeseries/master/commands/#tsincrbytsdecrby>`_.
 
         Args:
 
@@ -237,7 +237,7 @@ class TimeSeriesCommands:
         chunk_size:
             Each time-series uses chunks of memory of fixed size for time series samples.
             You can alter the default TSDB chunk size by passing the chunk_size argument (in Bytes).
-        """
+        """  # noqa
         timestamp = kwargs.get("timestamp", None)
         retention_msecs = kwargs.get("retention_msecs", None)
         uncompressed = kwargs.get("uncompressed", False)
@@ -260,7 +260,7 @@ class TimeSeriesCommands:
         and end data points will also be deleted.
         Return the count for deleted items.
         For more information see
-        `TS.DEL <https://oss.redis.com/redistimeseries/master/commands/#tsdel>`_. # noqa
+        `TS.DEL <https://oss.redis.com/redistimeseries/master/commands/#tsdel>`_.
 
         Args:
 
@@ -270,7 +270,7 @@ class TimeSeriesCommands:
             Start timestamp for the range deletion.
         to_time:
             End timestamp for the range deletion.
-        """
+        """  # noqa
         return self.execute_command(DEL_CMD, key, from_time, to_time)
 
     def createrule(
@@ -286,8 +286,8 @@ class TimeSeriesCommands:
         [`avg`, `sum`, `min`, `max`, `range`, `count`, `first`, `last`,
         `std.p`, `std.s`, `var.p`, `var.s`]
         For more information see
-        `TS.CREATERULE <https://oss.redis.com/redistimeseries/master/commands/#tscreaterule>`_. # noqa
-        """
+        `TS.CREATERULE <https://oss.redis.com/redistimeseries/master/commands/#tscreaterule>`_.
+        """  # noqa
         params = [source_key, dest_key]
         self._appendAggregation(params, aggregation_type, bucket_size_msec)
 
@@ -297,8 +297,8 @@ class TimeSeriesCommands:
         """
         Delete a compaction rule.
         For more information see
-        `TS.DELETERULE <https://oss.redis.com/redistimeseries/master/commands/#tsdeleterule>`_. # noqa
-        """
+        `TS.DELETERULE <https://oss.redis.com/redistimeseries/master/commands/#tsdeleterule>`_.
+        """  # noqa
         return self.execute_command(DELETERULE_CMD, source_key, dest_key)
 
     def __range_params(
@@ -344,7 +344,7 @@ class TimeSeriesCommands:
         """
         Query a range in forward direction for a specific time-serie.
         For more information see
-        `TS.RANGE <https://oss.redis.com/redistimeseries/master/commands/#tsrangetsrevrange>`_. # noqa
+        `TS.RANGE <https://oss.redis.com/redistimeseries/master/commands/#tsrangetsrevrange>`_.
 
         Args:
 
@@ -374,7 +374,7 @@ class TimeSeriesCommands:
             by_min_value).
         align:
             Timestamp for alignment control for aggregation.
-        """
+        """  # noqa
         params = self.__range_params(
             key,
             from_time,
@@ -405,7 +405,7 @@ class TimeSeriesCommands:
         """
         Query a range in reverse direction for a specific time-series.
         For more information see
-        `TS.REVRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsrangetsrevrange>`_.  # noqa
+        `TS.REVRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsrangetsrevrange>`_.
 
         **Note**: This command is only available since RedisTimeSeries >= v1.4
 
@@ -432,7 +432,7 @@ class TimeSeriesCommands:
             Filter result by maximum value (must mention also filter_by_min_value).
         align:
             Timestamp for alignment control for aggregation.
-        """
+        """  # noqa
         params = self.__range_params(
             key,
             from_time,
@@ -501,7 +501,7 @@ class TimeSeriesCommands:
         """
         Query a range across multiple time-series by filters in forward direction.
         For more information see
-        `TS.MRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsmrangetsmrevrange>`_.  # noqa
+        `TS.MRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsmrangetsmrevrange>`_.
 
         Args:
 
@@ -544,7 +544,7 @@ class TimeSeriesCommands:
             pair labels of a series.
         align:
             Timestamp for alignment control for aggregation.
-        """
+        """  # noqa
         params = self.__mrange_params(
             aggregation_type,
             bucket_size_msec,
@@ -584,7 +584,7 @@ class TimeSeriesCommands:
         """
         Query a range across multiple time-series by filters in reverse direction.
         For more information see
-        `TS.MREVRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsmrangetsmrevrange>`_. # noqa
+        `TS.MREVRANGE <https://oss.redis.com/redistimeseries/master/commands/#tsmrangetsmrevrange>`_.
 
         Args:
 
@@ -629,7 +629,7 @@ class TimeSeriesCommands:
             labels of a series.
         align:
             Timestamp for alignment control for aggregation.
-        """
+        """  # noqa
         params = self.__mrange_params(
             aggregation_type,
             bucket_size_msec,
@@ -653,14 +653,14 @@ class TimeSeriesCommands:
         """ # noqa
         Get the last sample of `key`.
         For more information see `TS.GET <https://oss.redis.com/redistimeseries/master/commands/#tsget>`_.
-        """
+        """  # noqa
         return self.execute_command(GET_CMD, key)
 
     def mget(self, filters, with_labels=False):
         """ # noqa
         Get the last samples matching the specific `filter`.
         For more information see `TS.MGET <https://oss.redis.com/redistimeseries/master/commands/#tsmget>`_.
-        """
+        """  # noqa
         params = []
         self._appendWithLabels(params, with_labels)
         params.extend(["FILTER"])
@@ -671,14 +671,14 @@ class TimeSeriesCommands:
         """  # noqa
         Get information of `key`.
         For more information see `TS.INFO <https://oss.redis.com/redistimeseries/master/commands/#tsinfo>`_.
-        """
+        """  # noqa
         return self.execute_command(INFO_CMD, key)
 
     def queryindex(self, filters):
         """  # noqa
         Get all the keys matching the `filter` list.
         For more information see `TS.QUERYINDEX <https://oss.redis.com/redistimeseries/master/commands/#tsqueryindex>`_.
-        """
+        """  # noqa
         return self.execute_command(QUERYINDEX_CMD, *filters)
 
     @staticmethod
diff --git a/tasks.py b/tasks.py
index 137d177..e482194 100644
--- a/tasks.py
+++ b/tasks.py
@@ -21,6 +21,12 @@ def devenv(c):
 
 
 @task
+def build_docs(c):
+    """Generates the sphinx documentation."""
+    run("tox -e docs")
+
+
+@task
 def linters(c):
     """Run code linters"""
     run("tox -e linters")
diff --git a/tox.ini b/tox.ini
index 0a94db8..33c3971 100644
--- a/tox.ini
+++ b/tox.ini
@@ -8,7 +8,7 @@ markers =
 [tox]
 minversion = 3.2.0
 requires = tox-docker
-envlist = {standalone,cluster}-{plain,hiredis}-{py35,py36,py37,py38,py39,pypy3},linters
+envlist = {standalone,cluster}-{plain,hiredis}-{py35,py36,py37,py38,py39,pypy3},linters,docs
 
 [docker:master]
 name = master
@@ -128,7 +128,7 @@ commands = /usr/bin/echo
 
 [testenv:linters]
 deps_files = dev_requirements.txt
-docker=
+docker =
 commands =
     flake8
     vulture redis whitelist.py --min-confidence 80
@@ -141,6 +141,13 @@ basepython = pypy3
 [testenv:pypy3-hiredis]
 basepython = pypy3
 
+[testenv:docs]
+deps_files = docs/requirements.txt
+docker =
+changedir = {toxinidir}/docs
+allowlist_externals = make
+commands = make html
+
 [flake8]
 exclude =
     *.egg-info,