Merge pull request #323 from openedx/swagger2rst

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

@@ -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/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

@@ -252,9 +252,8 @@ 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

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

requirements/doc.txt

@@ -36,8 +36,6 @@ billiard==4.2.0
     # via
     #   -r requirements/base.txt
     #   celery
-cached-property==1.5.2
-    # via swagger2rst
 celery==5.3.6
     # via
     #   -c requirements/constraints.txt
@@ -73,6 +71,8 @@ coreapi==2.3.3
     #   openapi-codec
 coreschema==0.0.4
     # via coreapi
+deepmerge==1.1.0
+    # via sphinxcontrib-openapi
 cryptography==41.0.7
     # via secretstorage
 django==3.2.23
@@ -100,6 +100,7 @@ docutils==0.19
     #   readme-renderer
     #   restructuredtext-lint
     #   sphinx
+    #   sphinx-mdinclude
 drf-yasg==1.21.7
     # via -r requirements/base.txt
 idna==3.6
@@ -132,9 +133,8 @@ jinja2==3.1.2
     # via
     #   coreschema
     #   sphinx
-    #   swagger2rst
 jsonschema==4.20.0
-    # via swagger2rst
+    # via sphinxcontrib-openapi
 jsonschema-specifications==2023.11.2
     # via jsonschema
 keyring==24.3.0
@@ -149,6 +149,8 @@ markupsafe==2.1.3
     # via jinja2
 mdurl==0.1.2
     # via markdown-it-py
+mistune==2.0.5
+    # via sphinx-mdinclude
 more-itertools==10.1.0
     # via jaraco-classes
 nh3==0.2.15
@@ -163,6 +165,8 @@ packaging==23.2
     #   sphinx
 pbr==6.0.0
     # via stevedore
+picobox==4.0.0
+    # via sphinxcontrib-openapi
 pkginfo==1.9.6
     # via twine
 pkgutil-resolve-name==1.3.10
@@ -183,6 +187,7 @@ pygments==2.17.2
     #   readme-renderer
     #   rich
     #   sphinx
+    #   sphinx-mdinclude
 python-dateutil==2.8.2
     # via
     #   -r requirements/base.txt
@@ -194,12 +199,11 @@ pytz==2023.3.post1
     #   django
     #   djangorestframework
     #   drf-yasg
-pyyaml==5.4.1
+pyyaml==6.0.1
     # via
-    #   -c requirements/constraints.txt
     #   -r requirements/base.txt
     #   drf-yasg
-    #   swagger2rst
+    #   sphinxcontrib-openapi
 readme-renderer==42.0
     # via twine
 referencing==0.32.0
@@ -234,6 +238,7 @@ six==1.16.0
     # via
     #   -r requirements/base.txt
     #   python-dateutil
+    #   sphinxcontrib-httpdomain
 snowballstemmer==2.2.0
     # via sphinx
 soupsieve==2.5
@@ -243,16 +248,24 @@ sphinx==6.2.1
     #   -r requirements/doc.in
     #   pydata-sphinx-theme
     #   sphinx-book-theme
+    #   sphinxcontrib-httpdomain
+    #   sphinxcontrib-openapi
 sphinx-book-theme==1.0.1
     # via -r requirements/doc.in
+sphinx-mdinclude==0.5.3
+    # via sphinxcontrib-openapi
 sphinxcontrib-applehelp==1.0.4
     # via sphinx
 sphinxcontrib-devhelp==1.0.2
     # via sphinx
 sphinxcontrib-htmlhelp==2.0.1
     # via sphinx
+sphinxcontrib-httpdomain==1.8.1
+    # via sphinxcontrib-openapi
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-openapi==0.8.3
+    # via -r requirements/doc.in
 sphinxcontrib-qthelp==1.0.3
     # via sphinx
 sphinxcontrib-serializinghtml==1.1.5
@@ -263,10 +276,6 @@ sqlparse==0.4.4
     #   django
 stevedore==5.1.0
     # via doc8
-strict-rfc3339==0.7
-    # via swagger2rst
-swagger2rst==0.0.4
-    # via -r requirements/doc.in
 tomli==2.0.1
     # via doc8
 twine==4.0.2

requirements/quality.txt

@@ -55,10 +55,8 @@ pylint-plugin-utils==0.8.2
     #   pylint-django
 python-slugify==8.0.1
     # via code-annotations
-pyyaml==5.4.1
-    # via
-    #   -c requirements/constraints.txt
-    #   code-annotations
+pyyaml==6.0.1
+    # via code-annotations
 six==1.16.0
     # via edx-lint
 snowballstemmer==2.2.0

requirements/test.txt

@@ -106,9 +106,8 @@ pytz==2023.3.post1
     #   django
     #   djangorestframework
     #   drf-yasg
-pyyaml==5.4.1
+pyyaml==6.0.1
     # via
-    #   -c requirements/constraints.txt
     #   -r requirements/base.txt
     #   drf-yasg
 rules==3.3