Modernization

.github/workflows/tests.yml

@@ -8,12 +8,12 @@ jobs:
   pre-commit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
-      - name: Set up Python 3.13
-        uses: actions/setup-python@v4
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Run pre-commit
         run: |
@@ -24,14 +24,14 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+        python-version: ['3.10', '3.11', '3.12', '3.13', '3.14']
 
     runs-on: ${{ matrix.os }}
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v6
 
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
 
@@ -47,12 +47,12 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
-      - name: Set up Python 3.13
-        uses: actions/setup-python@v4
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Run sphinx
         run: |
@@ -63,12 +63,12 @@ jobs:
     runs-on: ubuntu-latest
     if: github.event_name == 'push'
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v6
 
-      - name: Set up Python 3.13
-        uses: actions/setup-python@v4
+      - name: Set up Python 3.14
+        uses: actions/setup-python@v6
         with:
-          python-version: '3.13'
+          python-version: '3.14'
 
       - name: Prepare artifacts
         run: |

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "OpenAPI-Specification"]
-	path = tests/OpenAPI-Specification
-	url = https://github.com/OAI/OpenAPI-Specification.git

.pre-commit-config.yaml

@@ -1,20 +1,22 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v5.0.0
+    rev: v6.0.0
     hooks:
       - id: trailing-whitespace
+        exclude: 'tests/examples'
       - id: end-of-file-fixer
         exclude: >
           (?x)(
-            tests/renderers/httpdomain/rendered
+            tests/renderers/httpdomain/rendered |
+            tests/examples/
           )
       - id: check-docstring-first
       - id: check-json
       - id: check-yaml
       - id: debug-statements
 
   - repo: https://github.com/psf/black
-    rev: 24.10.0
+    rev: 26.1.0
     hooks:
       - id: black
         args: [--line-length=88, --target-version=py35]
@@ -46,6 +48,6 @@ repos:
           )
 
   - repo: https://github.com/pycqa/flake8
-    rev: 7.1.1
+    rev: 7.3.0
     hooks:
       - id: flake8

docs/conf.py

@@ -20,7 +20,4 @@
 pygments_style = "default"
 
 if not os.environ.get("READTHEDOCS") == "True":
-    import sphinx_rtd_theme
-
     html_theme = "sphinx_rtd_theme"
-    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["setuptools>=64.0.0", "setuptools_scm>=8.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sphinxcontrib-openapi"
+description = "OpenAPI (fka Swagger) spec renderer for Sphinx"
+readme = "README.rst"
+license = "BSD-3-Clause"
+authors = [
+    {name = "Ihor Kalnytskyi", email = "ihor@kalnytskyi.com"},
+]
+keywords = ["sphinx", "openapi", "swagger", "rest", "api", "renderer", "docs"]
+classifiers = [
+    "Topic :: Documentation",
+    "Topic :: Documentation :: Sphinx",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: Implementation :: CPython",
+    "Framework :: Setuptools Plugin",
+    "Framework :: Sphinx",
+    "Framework :: Sphinx :: Extension",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "sphinx >= 2.0",
+    "sphinxcontrib-httpdomain >= 1.5.0",
+    "PyYAML >= 3.12",
+    "jsonschema >= 2.5.1",
+    "sphinx-mdinclude >= 0.5.2",
+    "picobox >= 2.2",
+    "deepmerge >= 0.1",
+]
+dynamic = ["version"]
+
+[project.urls]
+Homepage = "https://github.com/sphinx-contrib/openapi"
+Documentation = "https://sphinxcontrib-openapi.readthedocs.io/"
+Source = "https://github.com/sphinx-contrib/openapi"
+Bugs = "https://github.com/sphinx-contrib/openapi/issues"
+
+[tool.setuptools]
+zip-safe = false
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["sphinxcontrib.*"]
+
+[tool.setuptools_scm]

sphinxcontrib/openapi/_lib2to3.py

@@ -5,7 +5,6 @@
 
 import picobox
 
-
 __all__ = [
     "convert",
 ]

sphinxcontrib/openapi/openapi31.py

@@ -1,11 +1,11 @@
 """
-    sphinxcontrib.openapi.openapi31
-    -------------------------------
+sphinxcontrib.openapi.openapi31
+-------------------------------
 
-    The OpenAPI 3.1 spec renderer. Based on ``sphinxcontrib-httpdomain``.
+The OpenAPI 3.1 spec renderer. Based on ``sphinxcontrib-httpdomain``.
 
-    :copyright: (c) 2016, Ihor Kalnytskyi.
-    :license: BSD, see LICENSE for details.
+:copyright: (c) 2016, Ihor Kalnytskyi.
+:license: BSD, see LICENSE for details.
 """
 
 import copy
@@ -24,7 +24,6 @@
 
 from sphinxcontrib.openapi import utils
 
-
 LOG = logging.getLogger(__name__)
 
 # Based on the spec:
@@ -341,13 +340,21 @@ def _get_type_from_schema(schema):
         request_content = properties.get("requestBody", {}).get("content", {})
         if request_content and "application/json" in request_content:
             schema = request_content["application/json"]["schema"]
-            req_properties = json.dumps(
-                schema["properties"], indent=2, separators=(",", ":")
-            )
+
             yield "{indent}**Request body:**".format(**locals())
             yield ""
             yield "{indent}.. sourcecode:: json".format(**locals())
             yield ""
+
+            if schema["type"] == "object":
+                # if it's an object, focus on the properties of that object
+                req_properties = json.dumps(
+                    schema["properties"], indent=2, separators=(",", ":")
+                )
+            else:
+                # if it's another type, dump the whole thing
+                req_properties = json.dumps(schema, indent=2, separators=(",", ":"))
+
             for line in req_properties.splitlines():
                 # yield indent + line
                 yield "{indent}{indent}{line}".format(**locals())

sphinxcontrib/openapi/renderers/__init__.py

@@ -4,7 +4,6 @@
 from ._httpdomain_old import HttpdomainOldRenderer
 from ._httpdomain import HttpdomainRenderer
 
-
 __all__ = [
     "abc",
     "HttpdomainOldRenderer",

sphinxcontrib/openapi/schema_utils.py

@@ -2,7 +2,6 @@
 
 from io import StringIO
 
-
 _DEFAULT_EXAMPLES = {
     "string": "string",
     "integer": 1,

tests/examples/.source

@@ -0,0 +1 @@
+https://github.com/OAI/learn.openapis.org/tree/b46517f32fb3f03595232b03c85de6e48a90abd5/examples

tests/examples/README.rst

@@ -0,0 +1,27 @@
+OpenAPI Examples
+================
+
+A copy of the examples taken from `github.com/OAI/learn.openapis.org`__
+
+This can be updated like so:
+
+.. code-block:: bash
+
+   # clone repo
+   git clone --depth 1 https://github.com/OAI/learn.openapis.org.git /tmp/learn-openapis
+
+   # copy updates
+   rm -rf tests/examples
+   cp -r /tmp/learn-openapis/examples tests/examples
+
+   # store commit
+   echo "https://github.com/OAI/learn.openapis.org/tree/$(git -C /tmp/learn-openapis rev-parse HEAD)/examples" > tests/examples/.source
+
+   # restore README and remove unnecessary index file
+   git checkout -f HEAD -- tests/examples/README.rst
+   rm tests/examples/index.md
+
+   # delete clone
+   rm -rf /tmp/learn-openapis
+
+.. __: https://github.com/OAI/learn.openapis.org.git

tests/examples/index.md

@@ -0,0 +1,9 @@
+---
+layout: default
+title: Example API Descriptions
+nav_order: 8
+has_children: true
+has_toc: true
+---
+
+# Example API Descriptions