Splitting documentation for read the docs (#1743)

chayim · web-flow · commit f4519f3b7f1f · 2021-11-25T16:03:30.000+02:00
diff --git 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
@@ -0,0 +1,5 @@
+Backoff
+#############
+
+.. automodule:: redis.backoff
+    :members: 
diff --git a/docs/conf.py b/docs/conf.py
@@ -29,7 +29,8 @@
 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 @@
 # 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 @@
 # 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
@@ -0,0 +1,12 @@
+Connecting to Redis
+#####################
+
+Generic Client
+**************
+.. autoclass:: redis.client.Redis
+    :members:
+
+Connection Pools
+*****************
+.. autoclass:: redis.connection.ConnectionPool
+    :members:
diff --git a/docs/exceptions.rst b/docs/exceptions.rst
@@ -0,0 +1,7 @@
+
+
+Exceptions
+##########
+
+.. automodule:: redis.exceptions
+    :members:
diff --git a/docs/genindex.rst b/docs/genindex.rst
@@ -0,0 +1,2 @@
+Module Index
+============
diff --git 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>`_.
diff --git a/docs/lock.rst b/docs/lock.rst
@@ -0,0 +1,5 @@
+Lock
+#########
+
+.. automodule:: redis.lock
+    :members: 
diff --git a/docs/redis_core_commands.rst 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:
diff --git a/docs/redismodules.rst 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
diff --git 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
@@ -0,0 +1,5 @@
+Retry Helpers
+#############
+
+.. automodule:: redis.retry
+    :members: 
diff --git a/docs/sentinel_commands.rst 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:
diff --git a/redis/commands/timeseries/commands.py b/redis/commands/timeseries/commands.py
diff --git a/tasks.py b/tasks.py
diff --git a/tox.ini b/tox.ini

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`sphinx<2`
`2`	`2`	`docutils<0.18`
	`3`	`+sphinx-rtd-theme`