Treat warnings as error in doc generation (#2097)

* Treat warnings as error in doc generation
* Fix doc generation issues
* Removed sphinx_rtd_theme from docs conf file

Author: pranavrth

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build

docs/conf.py

@@ -12,7 +12,6 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sphinx_rtd_theme
 import os
 try:
     import tomllib
@@ -133,7 +132,6 @@ def _read_version_from_pyproject(pyproject_path=None):
 # 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_path = [sphinx_rtd_theme.get_html_theme_path()]
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []

src/confluent_kafka/__init__.py

@@ -27,6 +27,7 @@
     TopicCollection,
     TopicPartitionInfo,
     IsolationLevel,
+    ElectionType
 )
 import os
 from .cimpl import (
@@ -74,6 +75,7 @@
     "IsolationLevel",
     "TopicCollection",
     "TopicPartitionInfo",
+    "ElectionType"
 ]
 
 

src/confluent_kafka/schema_registry/_async/avro.py

@@ -407,6 +407,7 @@ class AsyncAvroDeserializer(AsyncBaseDeserializer):
     | ``schema.id.deserializer``  | callable | Defines how the schema id/guid is deserialized.  |
     |                             |          | Defaults to dual_schema_id_deserializer.         |
     +-----------------------------+----------+--------------------------------------------------+
+
     Note:
         By default, Avro complex types are returned as dicts. This behavior can
         be overridden by registering a callable ``from_dict`` with the deserializer to

src/confluent_kafka/schema_registry/_async/json_schema.py

@@ -98,10 +98,9 @@ class AsyncJSONSerializer(AsyncBaseSerializer):
     | ``normalize.schemas``       | bool     | transform schemas to have a consistent format,     |
     |                             |          | including ordering properties and references.      |
     +-----------------------------+----------+----------------------------------------------------+
-    |                             |          | Whether to use the given schema ID for           |
-    | ``use.schema.id``           | int      | serialization.                                   |
-    |                             |          |                                                  |
-    +-----------------------------+----------+--------------------------------------------------+
+    |                             |          | Whether to use the given schema ID for             |
+    | ``use.schema.id``           | int      | serialization.                                     |
+    +-----------------------------+----------+----------------------------------------------------+
     |                             |          | Whether to use the latest subject version for      |
     | ``use.latest.version``      | bool     | serialization.                                     |
     |                             |          |                                                    |

src/confluent_kafka/schema_registry/_async/protobuf.py

@@ -57,6 +57,7 @@ async def _resolve_named_schema(
 ):
     """
     Resolves named schemas referenced by the provided schema recursively.
+
     :param schema: Schema to resolve named schemas for.
     :param schema_registry_client: AsyncSchemaRegistryClient to use for retrieval.
     :param pool: DescriptorPool to add resolved schemas to.
@@ -104,7 +105,7 @@ class AsyncProtobufSerializer(AsyncBaseSerializer):
     |                                     |          | Whether to use the given schema ID for               |
     | ``use.schema.id``                   | int      | serialization.                                       |
     |                                     |          |                                                      |
-    +-----------------------------------------+----------+--------------------------------------------------+
+    +-------------------------------------+----------+------------------------------------------------------+
     |                                     |          | Whether to use the latest subject version for        |
     | ``use.latest.version``              | bool     | serialization.                                       |
     |                                     |          |                                                      |

src/confluent_kafka/schema_registry/_async/schema_registry_client.py

@@ -634,7 +634,7 @@ async def register_schema(
                 Compatibility policy or is otherwise invalid.
 
         See Also:
-            `POST Subject API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions>`_
+            `POST Subject Version API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions>`_
         """  # noqa: E501
 
         registered_schema = await self.register_schema_full_response(subject_name, schema, normalize_schemas)
@@ -660,7 +660,7 @@ async def register_schema_full_response(
                 Compatibility policy or is otherwise invalid.
 
         See Also:
-            `POST Subject API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions>`_
+            `POST Subject Version API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions>`_
         """  # noqa: E501
 
         schema_id = self._cache.get_id_by_schema(subject_name, schema)
@@ -1114,7 +1114,7 @@ async def get_referenced_by(
             SchemaRegistryError: if the schema version can't be found or referenced schemas can't be retrieved
 
         See Also:
-            `GET Subject Versions API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#get--subjects-(string-%20subject)-versions-versionId-%20version-referencedby>`_
+            `GET Subject Versions (ReferenceBy) API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#get--subjects-(string-%20subject)-versions-versionId-%20version-referencedby>`_
         """  # noqa: E501
 
         query = {'offset': offset, 'limit': limit}
@@ -1142,7 +1142,7 @@ async def get_versions(
             SchemaRegistryError: If subject can't be found
 
         See Also:
-            `GET Subject Versions API Reference <https://docs.confluent.io/current/schema-registry/develop/api.html#post--subjects-(string-%20subject)-versions>`_
+            `GET Subject All Versions API Reference <https://docs.confluent.io/platform/current/schema-registry/develop/api.html#get--subjects-(string-%20subject)-versions>`_
         """  # noqa: E501
 
         query = {'deleted': deleted, 'deleted_only': deleted_only, 'offset': offset, 'limit': limit}

src/confluent_kafka/schema_registry/_sync/avro.py

@@ -407,6 +407,7 @@ class AvroDeserializer(BaseDeserializer):
     | ``schema.id.deserializer``  | callable | Defines how the schema id/guid is deserialized.  |
     |                             |          | Defaults to dual_schema_id_deserializer.         |
     +-----------------------------+----------+--------------------------------------------------+
+
     Note:
         By default, Avro complex types are returned as dicts. This behavior can
         be overridden by registering a callable ``from_dict`` with the deserializer to

src/confluent_kafka/schema_registry/_sync/json_schema.py

@@ -98,10 +98,9 @@ class JSONSerializer(BaseSerializer):
     | ``normalize.schemas``       | bool     | transform schemas to have a consistent format,     |
     |                             |          | including ordering properties and references.      |
     +-----------------------------+----------+----------------------------------------------------+
-    |                             |          | Whether to use the given schema ID for           |
-    | ``use.schema.id``           | int      | serialization.                                   |
-    |                             |          |                                                  |
-    +-----------------------------+----------+--------------------------------------------------+
+    |                             |          | Whether to use the given schema ID for             |
+    | ``use.schema.id``           | int      | serialization.                                     |
+    +-----------------------------+----------+----------------------------------------------------+
     |                             |          | Whether to use the latest subject version for      |
     | ``use.latest.version``      | bool     | serialization.                                     |
     |                             |          |                                                    |

src/confluent_kafka/schema_registry/_sync/protobuf.py

@@ -57,6 +57,7 @@ def _resolve_named_schema(
 ):
     """
     Resolves named schemas referenced by the provided schema recursively.
+
     :param schema: Schema to resolve named schemas for.
     :param schema_registry_client: SchemaRegistryClient to use for retrieval.
     :param pool: DescriptorPool to add resolved schemas to.
@@ -104,7 +105,7 @@ class ProtobufSerializer(BaseSerializer):
     |                                     |          | Whether to use the given schema ID for               |
     | ``use.schema.id``                   | int      | serialization.                                       |
     |                                     |          |                                                      |
-    +-----------------------------------------+----------+--------------------------------------------------+
+    +-------------------------------------+----------+------------------------------------------------------+
     |                                     |          | Whether to use the latest subject version for        |
     | ``use.latest.version``              | bool     | serialization.                                       |
     |                                     |          |                                                      |