Ditch swagger2rst dependency

docs/conf.py

@@ -49,6 +49,7 @@
     'sphinx.ext.doctest',
     'sphinx.ext.intersphinx',
     'sphinx.ext.ifconfig',
+    'sphinxcontrib.openapi',
 ]
 
 # A list of warning types to suppress arbitrary warning messages.
@@ -488,30 +489,27 @@
 
 def on_init(app):  # pylint: disable=unused-argument
     """
-    Run sphinx-apidoc and swg2rst after Sphinx initialization.
+    Run sphinx-apidoc after Sphinx initialization.
 
     Read the Docs won't run tox or custom shell commands, so we need this to
     avoid checking in the generated reStructuredText files.
     """
     docs_path = os.path.abspath(os.path.dirname(__file__))
     root_path = os.path.abspath(os.path.join(docs_path, '..'))
     apidoc_path = 'sphinx-apidoc'
-    swg2rst_path = 'swg2rst'
+
     if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
         # If we are, assemble the path manually
         bin_path = os.path.abspath(os.path.join(sys.prefix, 'bin'))
         apidoc_path = os.path.join(bin_path, apidoc_path)
-        swg2rst_path = os.path.join(bin_path, swg2rst_path)
+
     check_call([apidoc_path, '-o', docs_path, os.path.join(root_path, 'user_tasks'),
                 os.path.join(root_path, 'user_tasks/migrations')])
-    json_path = os.path.join(docs_path, 'swagger.json')
-    rst_path = os.path.join(docs_path, 'rest_api.rst')
-    check_call([swg2rst_path, json_path, '-f', 'rst', '-o', rst_path])
 
 
 def setup(app):
     """
-    Sphinx extension: run sphinx-apidoc and swg2rst.
+    Sphinx extension: run sphinx-apidoc.
     """
     event = 'builder-inited'
     app.connect(event, on_init)

docs/readme.rst

@@ -1 +1,3 @@
 .. include:: ../README.rst
+
+.. openapi:: swagger.json

requirements/base.txt

@@ -51,7 +51,7 @@ kombu==5.3.4
     # via celery
 packaging==23.2
     # via drf-yasg
-prompt-toolkit==3.0.41
+prompt-toolkit==3.0.43
     # via click-repl
 python-dateutil==2.8.2
     # via celery
@@ -60,10 +60,8 @@ pytz==2023.3.post1
     #   django
     #   djangorestframework
     #   drf-yasg
-pyyaml==5.4.1
-    # via
-    #   -c requirements/constraints.txt
-    #   drf-yasg
+pyyaml==6.0.1
+    # via drf-yasg
 six==1.16.0
     # via python-dateutil
 sqlparse==0.4.4

requirements/ci.txt

@@ -10,7 +10,7 @@ chardet==5.2.0
     # via tox
 colorama==0.4.6
     # via tox
-distlib==0.3.7
+distlib==0.3.8
     # via virtualenv
 filelock==3.13.1
     # via

requirements/constraints.txt

@@ -13,8 +13,3 @@
 -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt
 
 celery<6.0
-
-# pyyaml==6.0 made the `Loader` a necessary argument for `yaml.load()` function.
-# swagger2rst uses pyyaml and fails with the new version hence failing the `make docs` command.
-# This constraint can be removed once the https://github.com/Arello-Mobile/swagger2rst/issues/10 is done.
-pyyaml<6.0

requirements/dev.txt

@@ -8,15 +8,11 @@ amqp==5.2.0
     # via
     #   -r requirements/test.txt
     #   kombu
-annotated-types==0.6.0
-    # via
-    #   -r requirements/quality.txt
-    #   pydantic
 asgiref==3.7.2
     # via
     #   -r requirements/test.txt
     #   django
-astroid==3.0.1
+astroid==3.0.2
     # via
     #   -r requirements/quality.txt
     #   pylint
@@ -43,22 +39,10 @@ celery==5.3.6
     # via
     #   -c requirements/constraints.txt
     #   -r requirements/test.txt
-cerberus==1.3.5
-    # via
-    #   -r requirements/quality.txt
-    #   plette
-certifi==2023.11.17
-    # via
-    #   -r requirements/quality.txt
-    #   requests
 chardet==5.2.0
     # via
     #   -r requirements/ci.txt
     #   tox
-charset-normalizer==3.3.2
-    # via
-    #   -r requirements/quality.txt
-    #   requests
 click==8.1.7
     # via
     #   -r requirements/pip-tools.txt
@@ -105,11 +89,9 @@ dill==0.3.7
     # via
     #   -r requirements/quality.txt
     #   pylint
-distlib==0.3.7
+distlib==0.3.8
     # via
     #   -r requirements/ci.txt
-    #   -r requirements/quality.txt
-    #   requirementslib
     #   virtualenv
 django==3.2.23
     # via
@@ -125,10 +107,6 @@ djangorestframework==3.14.0
     # via
     #   -r requirements/test.txt
     #   drf-yasg
-docopt==0.6.2
-    # via
-    #   -r requirements/quality.txt
-    #   pipreqs
 drf-yasg==1.21.7
     # via -r requirements/test.txt
 edx-i18n-tools==1.3.0
@@ -146,10 +124,6 @@ filelock==3.13.1
     #   -r requirements/ci.txt
     #   tox
     #   virtualenv
-idna==3.6
-    # via
-    #   -r requirements/quality.txt
-    #   requests
 importlib-metadata==7.0.0
     # via
     #   -r requirements/pip-tools.txt
@@ -162,7 +136,7 @@ iniconfig==2.0.0
     # via
     #   -r requirements/test.txt
     #   pytest
-isort==5.13.0
+isort==5.13.2
     # via
     #   -r requirements/quality.txt
     #   pylint
@@ -202,33 +176,15 @@ pbr==6.0.0
     # via
     #   -r requirements/quality.txt
     #   stevedore
-pep517==0.13.1
-    # via
-    #   -r requirements/quality.txt
-    #   requirementslib
-pip-api==0.0.30
-    # via
-    #   -r requirements/quality.txt
-    #   isort
 pip-tools==7.3.0
     # via -r requirements/pip-tools.txt
-pipreqs==0.4.13
-    # via
-    #   -r requirements/quality.txt
-    #   isort
 platformdirs==4.1.0
     # via
     #   -r requirements/ci.txt
     #   -r requirements/quality.txt
     #   pylint
-    #   requirementslib
     #   tox
     #   virtualenv
-plette[validation]==0.4.4
-    # via
-    #   -r requirements/quality.txt
-    #   plette
-    #   requirementslib
 pluggy==1.3.0
     # via
     #   -r requirements/ci.txt
@@ -237,23 +193,15 @@ pluggy==1.3.0
     #   tox
 polib==1.2.0
     # via edx-i18n-tools
-prompt-toolkit==3.0.41
+prompt-toolkit==3.0.43
     # via
     #   -r requirements/test.txt
     #   click-repl
 pycodestyle==2.11.1
     # via -r requirements/quality.txt
-pydantic==2.5.2
-    # via
-    #   -r requirements/quality.txt
-    #   requirementslib
-pydantic-core==2.14.5
-    # via
-    #   -r requirements/quality.txt
-    #   pydantic
 pydocstyle==6.3.0
     # via -r requirements/quality.txt
-pylint==3.0.2
+pylint==3.0.3
     # via
     #   -r requirements/quality.txt
     #   edx-lint
@@ -304,23 +252,13 @@ pytz==2023.3.post1
     #   django
     #   djangorestframework
     #   drf-yasg
-pyyaml==5.4.1
+pyyaml==6.0.1
     # via
-    #   -c requirements/constraints.txt
     #   -r requirements/quality.txt
     #   -r requirements/test.txt
     #   code-annotations
     #   drf-yasg
     #   edx-i18n-tools
-requests==2.31.0
-    # via
-    #   -r requirements/quality.txt
-    #   requirementslib
-    #   yarg
-requirementslib==3.0.0
-    # via
-    #   -r requirements/quality.txt
-    #   isort
 rules==3.3
     # via -r requirements/test.txt
 six==1.16.0
@@ -355,7 +293,6 @@ tomli==2.0.1
     #   -r requirements/test.txt
     #   build
     #   coverage
-    #   pep517
     #   pip-tools
     #   pylint
     #   pyproject-api
@@ -365,21 +302,16 @@ tomli==2.0.1
 tomlkit==0.12.3
     # via
     #   -r requirements/quality.txt
-    #   plette
     #   pylint
-    #   requirementslib
 tox==4.11.4
     # via -r requirements/ci.txt
 typing-extensions==4.9.0
     # via
     #   -r requirements/quality.txt
     #   -r requirements/test.txt
-    #   annotated-types
     #   asgiref
     #   astroid
     #   kombu
-    #   pydantic
-    #   pydantic-core
     #   pylint
 tzdata==2023.3
     # via
@@ -390,10 +322,6 @@ uritemplate==4.1.1
     # via
     #   -r requirements/test.txt
     #   drf-yasg
-urllib3==2.1.0
-    # via
-    #   -r requirements/quality.txt
-    #   requests
 vine==5.1.0
     # via
     #   -r requirements/test.txt
@@ -412,10 +340,6 @@ wheel==0.42.0
     # via
     #   -r requirements/pip-tools.txt
     #   pip-tools
-yarg==0.1.9
-    # via
-    #   -r requirements/quality.txt
-    #   pipreqs
 zipp==3.17.0
     # via
     #   -r requirements/pip-tools.txt

requirements/doc.in

@@ -8,5 +8,5 @@ doc8                      # reStructuredText style checker
 sphinx-book-theme         # Common theme for all Open edX projects
 rules                     # Needed to import user_tasks/rules.py for autodoc
 Sphinx                    # Documentation builder
-swagger2rst               # Generates REST API documentation for Sphinx from a Swagger/Open API schema JSON file
+sphinxcontrib-openapi
 twine                     # Validates the generated long description for PyPI