Merge pull request #18 from lsst-sqre/tickets/DM-37493

DM-37493: Add support for httpx
lsst-sqre · Jan 9, 2023 · c2a3ab6 · c2a3ab6
2 parents 1c3725b + 5cb90e9
commit c2a3ab6
Show file tree

Hide file tree

Showing 20 changed files with 180 additions and 271 deletions.
diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml
@@ -40,6 +40,7 @@ jobs:
           - "3.8"
           - "3.9"
           - "3.10"
+          - "3.11"
 
     steps:
       - uses: actions/checkout@v3

diff --git a/.github/workflows/periodic-ci.yaml b/.github/workflows/periodic-ci.yaml
@@ -18,6 +18,7 @@ jobs:
           - "3.8"
           - "3.9"
           - "3.10"
+          - "3.11"
 
     steps:
       - uses: actions/checkout@v3

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,19 +1,19 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.4.0
     hooks:
       - id: trailing-whitespace
       - id: check-yaml
       - id: check-toml
 
   - repo: https://github.com/pycqa/isort
-    rev: 5.10.1
+    rev: 5.11.4
     hooks:
       - id: isort
         additional_dependencies: [toml]
 
   - repo: https://github.com/psf/black
-    rev: 22.6.0
+    rev: 22.12.0
     hooks:
       - id: black
 
@@ -25,12 +25,12 @@ repos:
         args: [-l, '79', -t, py38]
 
   - repo: https://github.com/pycqa/pydocstyle
-    rev: 6.1.1
+    rev: 6.2.2
     hooks:
     - id: pydocstyle
-      additional_dependencies: [toml]
+      additional_dependencies: [tomli]
 
-  - repo: https://gitlab.com/pycqa/flake8
-    rev: 4.0.1
+  - repo: https://github.com/pycqa/flake8
+    rev: 6.0.0
     hooks:
       - id: flake8
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,15 @@
 # Change log
 
+## Unreleased
+
+New features:
+
+- New [HTTPX](https://www.python-httpx.org) support with `kafkit.registry.httpx.RegistryApi`, in addition to the existing aiohttp support.
+- Documentation is now built with the new Rubin Observatory user guide theme and Sphinx configuration.
+
 ## 0.2.1 (2022-07-15)
 
-A `py.typed` file is now included to advertise typo annotations in Kafkit.
+A `py.typed` file is now included to advertise type annotations in Kafkit.
 
 ## 0.2.0 (2022-07-15)
 

diff --git a/Makefile b/Makefile
@@ -5,7 +5,7 @@ help:
 
 .PHONY: init
 init:
-	pip install -e ".[dev]"
+	pip install -e ".[aiohttp,httpx,dev]"
 	pip install tox pre-commit
 	pre-commit install
 	rm -rf .tox
diff --git a/docs/_rst_epilog.rst b/docs/_rst_epilog.rst
@@ -0,0 +1,12 @@
+
+.. _aiohttp: https://aiohttp.readthedocs.io/en/stable/
+.. _aiokafka: https://aiokafka.readthedocs.io/en/stable/
+.. _Confluent Schema Registry: https://docs.confluent.io/current/schema-registry/docs/index.html
+.. _Confluent Wire Format: https://docs.confluent.io/current/schema-registry/docs/serializer-formatter.html#wire-format
+.. _HTTPX: https://www.python-httpx.org
+.. _mypy: http://www.mypy-lang.org
+.. _pre-commit: https://pre-commit.com
+.. _pytest: https://docs.pytest.org/en/latest/
+.. _Schema Evolution and Compatibility: https://docs.confluent.io/current/schema-registry/avro.html
+.. _Strimzi: https://strimzi.io
+.. _tox: https://tox.readthedocs.io/en/latest/
diff --git a/docs/api.rst b/docs/api.rst
@@ -8,6 +8,9 @@ Kafkit API reference
 .. automodapi:: kafkit.registry.aiohttp
    :no-inheritance-diagram:
 
+.. automodapi:: kafkit.registry.httpx
+   :no-inheritance-diagram:
+
 .. automodapi:: kafkit.registry.manager
    :no-inheritance-diagram:
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -1,100 +1,5 @@
-import os
+from documenteer.conf.guide import *
 
-import lsst_sphinx_bootstrap_theme
-
-import kafkit
-
-# Common links and substitutions =============================================
-
-rst_epilog = """
-
-.. _aiohttp: https://aiohttp.readthedocs.io/en/stable/
-.. _aiokafka: https://aiokafka.readthedocs.io/en/stable/
-.. _Confluent Schema Registry: https://docs.confluent.io/current/schema-registry/docs/index.html
-.. _Confluent Wire Format: https://docs.confluent.io/current/schema-registry/docs/serializer-formatter.html#wire-format
-.. _mypy: http://www.mypy-lang.org
-.. _pre-commit: https://pre-commit.com
-.. _pytest: https://docs.pytest.org/en/latest/
-.. _Schema Evolution and Compatibility: https://docs.confluent.io/current/schema-registry/avro.html
-.. _Strimzi: https://strimzi.io
-.. _tox: https://tox.readthedocs.io/en/latest/
-"""
-
-# Extensions =================================================================
-
-extensions = [
-    "myst_parser",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.napoleon",
-    "sphinx.ext.doctest",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.todo",
-    "sphinx-prompt",
-    "sphinx_automodapi.automodapi",
-    "sphinx_automodapi.smart_resolver",
-    "documenteer.sphinxext",
-]
-
-# General configuration ======================================================
-
-source_suffix = {
-    ".rst": "restructuredtext",
-    ".txt": "markdown",
-    ".md": "markdown",
-}
-
-# The root toctree document.
-root_doc = "index"
-
-# General information about the project.
-project = "Kafkit"
-copyright = (
-    "2019-2022 "
-    "Association of Universities for Research in Astronomy, Inc. (AURA)"
-)
-author = "LSST Data Management"
-
-version = kafkit.__version__
-release = version
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-exclude_patterns = ["_build", "README.rst"]
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = "sphinx"
-
-# The reST default role cross-links Python (used for this markup: `text`)
-default_role = "py:obj"
-
-nitpick_ignore = [
-    # Ignore missing cross-references for modules that don't provide
-    # intersphinx.  The documentation itself should use double-quotes instead
-    # of single-quotes to not generate a reference, but automatic references
-    # are generated from the type signatures and can't be avoided.
-    ("py:obj", "aiokafka.AIOKafkaProducer.send_and_wait"),
-]
-
-# Intersphinx ================================================================
-
-intersphinx_mapping = {
-    "python": ("https://docs.python.org/3/", None),
-    "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
-    "aiokafka": ("https://aiokafka.readthedocs.io/en/stable/", None),
-    "fastavro": ("https://fastavro.readthedocs.io/en/latest/", None),
-}
-
-intersphinx_timeout = 10.0  # seconds
-intersphinx_cache_limit = 5  # days
-
-# Linkcheck builder ==========================================================
-
-linkcheck_retries = 2
-
-linkcheck_ignore = [
-    r"^https://jira.lsstcorp.org/browse/",
-    r"^http://registry:8081",
-]
 
 linkcheck_anchors_ignore = [
     r"^!",
@@ -104,122 +9,10 @@
     r"errors",
 ]
 
-linkcheck_timeout = 15
-
-# HTML builder ===============================================================
-
-templates_path = [
-    "_templates",
-    lsst_sphinx_bootstrap_theme.get_html_templates_path(),
-]
-
-html_theme = "lsst_sphinx_bootstrap_theme"
-html_theme_path = [lsst_sphinx_bootstrap_theme.get_html_theme_path()]
-
-html_context = {}
-
-# 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 = {"logotext": project}
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> documentation".
-html_title = f"{project} v{version}"
-
-# A shorter title for the navigation bar.  Default is the same as html_title.
-html_short_title = project
-
-# 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 = []
-
-# If true, links to the reST sources are added to the pages.
-html_show_sourcelink = False
-
-# Do not copy reST source for each page into the build
-html_copy_source = False
-
-# If false, no module index is generated.
-html_domain_indices = True
-
-# If false, no index is generated.
-html_use_index = True
-
-# API Reference ==============================================================
-
-napoleon_google_docstring = False
-napoleon_numpy_docstring = True
-napoleon_include_init_with_doc = False
-napoleon_include_private_with_doc = False
-napoleon_include_special_with_doc = True
-napoleon_use_admonition_for_examples = False
-napoleon_use_admonition_for_notes = False
-napoleon_use_admonition_for_references = False
-napoleon_use_ivar = False
-napoleon_use_keyword = True
-napoleon_use_param = True
-napoleon_use_rtype = True
-
 napoleon_type_aliases = {
     # resolves confusion between sans-io version of impl specific version
     "RegistryApi": "kafkit.registry.sansio.RegistryApi",
     # Napoleon doesn't resolve whats under TYPE_CHECKING
     "ClientSession": "aiohttp.ClientSession",
     "optional": "typing.Optional",
 }
-
-autosummary_generate = True
-
-automodapi_toctreedirnm = "api"
-automodsumm_inherited_members = True
-
-# Docstrings for classes and methods are inherited from parents.
-autodoc_inherit_docstrings = True
-
-# Class documentation should only contain the class docstring and
-# ignore the __init__ docstring, account to LSST coding standards.
-autoclass_content = "class"
-
-# Default flags for automodapi directives. Special members are dunder
-# methods.
-autodoc_default_options = {
-    "show-inheritance": True,
-    "special-members": True,
-}
-
-# Render inheritance diagrams in SVG
-graphviz_output_format = "svg"
-
-graphviz_dot_args = [
-    "-Nfontsize=10",
-    "-Nfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
-    "-Efontsize=10",
-    "-Efontname=Helvetica Neue, Helvetica, Arial, sans-serif",
-    "-Gfontsize=10",
-    "-Gfontname=Helvetica Neue, Helvetica, Arial, sans-serif",
-]
-
-# TODO extension =============================================================
-
-todo_include_todos = False
-
-# My-ST (Markdown) ===========================================================
-# https://myst-parser.readthedocs.io/en/latest/syntax/optional.html
-
-myst_enable_extensions = [
-    "amsmath",
-    "dollarmath",
-    "colon_fence",
-    "deflist",
-    "fieldlist",
-    "html_admonition",
-    "html_image",
-    "linkify",
-    "replacements",
-    "smartquotes",
-    "strikethrough",
-    "substitution",
-    "tasklist",
-]
diff --git a/docs/documenteer.toml b/docs/documenteer.toml
@@ -0,0 +1,28 @@
+[project]
+title = "Kafkit"
+copyright = "2019-2023 Association of Universities for Research in Astronomy, Inc. (AURA)"
+
+[project.python]
+package = "kafkit"
+
+[sphinx]
+rst_epilog_file = "_rst_epilog.rst"
+nitpick_ignore = [
+    [
+        "py:obj",
+        "aiokafka.AIOKafkaProducer.send_and_wait",
+    ],
+    [
+        "py:class",
+        "httpx.AsyncClient",
+    ],
+]
+
+[sphinx.intersphinx.projects]
+python = "https://docs.python.org/3/"
+aiohttp = "https://aiohttp.readthedocs.io/en/stable/"
+aiokafka = "https://aiokafka.readthedocs.io/en/stable/"
+fastavro = "https://fastavro.readthedocs.io/en/latest/"
+
+[sphinx.linkcheck]
+ignore = ['^https://jira.lsstcorp.org/browse/', '^http://registry:8081']
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
@@ -0,0 +1,9 @@
+##########
+User guide
+##########
+
+.. toctree::
+   :maxdepth: 2
+
+   recordnameschemamanager-howto
+   strimzi-ssl-howto
diff --git a/docs/recordnameschemamanager-howto.rst → docs/guide/recordnameschemamanager-howto.rst b/docs/recordnameschemamanager-howto.rst → docs/guide/recordnameschemamanager-howto.rst
diff --git a/docs/strimzi-ssl-howto.rst → docs/guide/strimzi-ssl-howto.rst b/docs/strimzi-ssl-howto.rst → docs/guide/strimzi-ssl-howto.rst