diff --git a/docs/conf.py b/docs/conf.py index ced01d5b..c22eaed6 100644 --- a/docs/conf.py +++ b/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,7 +489,7 @@ 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. @@ -496,22 +497,19 @@ def on_init(app): # pylint: disable=unused-argument 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) diff --git a/docs/readme.rst b/docs/readme.rst index 72a33558..2a344e58 100644 --- a/docs/readme.rst +++ b/docs/readme.rst @@ -1 +1,3 @@ .. include:: ../README.rst + +.. openapi:: swagger.json diff --git a/requirements/base.txt b/requirements/base.txt index ee4cc396..790a30fb 100644 --- a/requirements/base.txt +++ b/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 diff --git a/requirements/constraints.txt b/requirements/constraints.txt index 64c9d2f9..f61a3260 100644 --- a/requirements/constraints.txt +++ b/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 diff --git a/requirements/dev.txt b/requirements/dev.txt index 9d8ee97f..cfae2532 100644 --- a/requirements/dev.txt +++ b/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 diff --git a/requirements/doc.in b/requirements/doc.in index c4007e69..a43793af 100644 --- a/requirements/doc.in +++ b/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 diff --git a/requirements/doc.txt b/requirements/doc.txt index b58506fb..9f8925c9 100644 --- a/requirements/doc.txt +++ b/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 diff --git a/requirements/quality.txt b/requirements/quality.txt index a43c85f4..7328eb12 100644 --- a/requirements/quality.txt +++ b/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 diff --git a/requirements/test.txt b/requirements/test.txt index 1eeaf72d..ca5c0ffe 100644 --- a/requirements/test.txt +++ b/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