docs: fixup sphinx warnings (#3060)

Author: dpkp

docs/changelog.rst

@@ -1371,7 +1371,7 @@ Compatibility
 
 
 1.4.4 (Nov 20, 2018)
-##########
+####################
 
 Bugfixes
 --------

docs/conf.py

@@ -33,6 +33,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
+    'sphinx_rtd_theme',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -133,7 +134,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+#html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -262,10 +263,3 @@
 
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 #texinfo_no_detailmenu = False
-
-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()]

docs/install.rst

@@ -37,7 +37,7 @@ support https://pypi.python.org/pypi/crc32c package if it's installed.
 
 
 Optional ZSTD install
-********************
+*********************
 
 To enable ZSTD compression/decompression, install python-zstandard:
 

docs/usage.rst

@@ -219,7 +219,8 @@ KafkaProducer
 
 
 ClusterMetadata
-=============
+===============
+
 .. code:: python
 
     from kafka.cluster import ClusterMetadata
@@ -240,8 +241,10 @@ ClusterMetadata
 
 
 KafkaAdminClient
-=============
+================
+
 .. code:: python
+
     from kafka import KafkaAdminClient
     from kafka.admin import NewTopic
 

kafka/admin/_topics.py

@@ -94,12 +94,14 @@ def create_topics(self, new_topics, timeout_ms=None, validate_only=False, raise_
         """Create new topics in the cluster.
 
         Arguments:
-            new_topics: A list of topic names,
-                or a dict of {topic_name: {num_partitions: int (default -1),
-                                           replication_factor: int (default -1),
-                                           assignments: {partition: [broker_ids]},
-                                           configs: {key: value}}}
-                    All keys are optional.
+            new_topics: A list of topic names, or a dict mapping each topic
+                name to a dict of options (all keys optional)::
+
+                    {topic_name: {num_partitions: int (default -1),
+                                  replication_factor: int (default -1),
+                                  assignments: {partition: [broker_ids]},
+                                  configs: {key: value}}}
+
                 List of NewTopic objects is deprecated.
                 Note: for brokers < 2.4, num_partitions and replication_factor
                 are required and must be provided via dict or [NewTopic].

kafka/admin/client.py

@@ -134,8 +134,9 @@ class KafkaAdminClient(
             timeout (see bootstrap_timeout_ms below).
             Different versions enable different functionality.
 
-            Examples:
-                (4, 2) most recent broker release, enable all supported features
+            Examples::
+
+                (4, 3) most recent broker release, enable all supported features
                 (0, 11) enables message format v2 (internal)
                 (0, 10, 0) enables sasl authentication and message format v1
                 (0, 9) enables full group coordination features with automatic

kafka/consumer/group.py

@@ -229,8 +229,9 @@ class KafkaConsumer:
             timeout (see bootstrap_timeout_ms below).
             Different versions enable different functionality.
 
-            Examples:
-                (4, 2) most recent broker release, enable all supported features
+            Examples::
+
+                (4, 3) most recent broker release, enable all supported features
                 (0, 11) enables message format v2 (internal)
                 (0, 10, 0) enables sasl authentication and message format v1
                 (0, 9) enables full group coordination features with automatic

kafka/producer/kafka.py

@@ -346,8 +346,9 @@ class KafkaProducer:
             timeout (see bootstrap_timeout_ms below).
             Different versions enable different functionality.
 
-            Examples:
-                (4, 2) most recent broker release, enable all supported features
+            Examples::
+
+                (4, 3) most recent broker release, enable all supported features
                 (0, 11) enables message format v2 (internal)
                 (0, 10, 0) enables sasl authentication and message format v1
                 (0, 9) enables full group coordination features with automatic