From 0f54f0d24ef5a62d8c8880a105e5c95ebaae7bbd Mon Sep 17 00:00:00 2001 From: Irtaza Akram Date: Wed, 13 Dec 2023 11:00:20 +0500 Subject: [PATCH 1/3] feat: ditch swagger2rst dependency --- docs/conf.py | 11 ++--- requirements/base.txt | 8 ++-- requirements/ci.txt | 2 +- requirements/constraints.txt | 5 -- requirements/dev.txt | 88 +++--------------------------------- requirements/doc.in | 1 - requirements/doc.txt | 38 ++-------------- requirements/quality.txt | 68 ++++------------------------ requirements/test.txt | 5 +- 9 files changed, 28 insertions(+), 198 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index ced01d5b..8fb3b61c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -488,7 +488,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 +496,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/requirements/base.txt b/requirements/base.txt index 5b3dd426..bc88b2d6 100644 --- a/requirements/base.txt +++ b/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.42 # 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 diff --git a/requirements/ci.txt b/requirements/ci.txt index efd08147..5104079b 100644 --- a/requirements/ci.txt +++ b/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 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 661bdf23..f806e390 100644 --- a/requirements/dev.txt +++ b/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.1 # 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.42 # 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 diff --git a/requirements/doc.in b/requirements/doc.in index c4007e69..b32f3f10 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -8,5 +8,4 @@ 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 twine # Validates the generated long description for PyPI diff --git a/requirements/doc.txt b/requirements/doc.txt index e98945a5..f419cbbc 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -16,11 +16,7 @@ asgiref==3.7.2 # via # -r requirements/base.txt # django -attrs==23.1.0 - # via - # jsonschema - # referencing -babel==2.13.1 +babel==2.14.0 # via # pydata-sphinx-theme # sphinx @@ -36,8 +32,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 @@ -108,10 +102,7 @@ importlib-metadata==7.0.0 # sphinx # twine importlib-resources==6.1.1 - # via - # jsonschema - # jsonschema-specifications - # keyring + # via keyring inflection==0.5.1 # via # -r requirements/base.txt @@ -124,11 +115,6 @@ jinja2==3.1.2 # via # coreschema # sphinx - # swagger2rst -jsonschema==4.20.0 - # via swagger2rst -jsonschema-specifications==2023.11.2 - # via jsonschema keyring==24.3.0 # via twine kombu==5.3.4 @@ -157,9 +143,7 @@ pbr==6.0.0 # via stevedore pkginfo==1.9.6 # via twine -pkgutil-resolve-name==1.3.10 - # via jsonschema -prompt-toolkit==3.0.41 +prompt-toolkit==3.0.42 # via # -r requirements/base.txt # click-repl @@ -184,18 +168,12 @@ 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 readme-renderer==42.0 # via twine -referencing==0.32.0 - # via - # jsonschema - # jsonschema-specifications requests==2.31.0 # via # coreapi @@ -210,10 +188,6 @@ rfc3986==2.0.0 # via twine rich==13.7.0 # via twine -rpds-py==0.13.2 - # via - # jsonschema - # referencing rules==3.3 # via -r requirements/doc.in simplejson==3.19.2 @@ -251,10 +225,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 a65bacf3..cc5003d8 100644 --- a/requirements/quality.txt +++ b/requirements/quality.txt @@ -4,18 +4,10 @@ # # make upgrade # -annotated-types==0.6.0 - # via pydantic -astroid==3.0.1 +astroid==3.0.2 # via # pylint # pylint-celery -cerberus==1.3.5 - # via plette -certifi==2023.11.17 - # via requests -charset-normalizer==3.3.2 - # via requests click==8.1.7 # via # click-log @@ -27,15 +19,9 @@ code-annotations==1.5.0 # via edx-lint dill==0.3.7 # via pylint -distlib==0.3.7 - # via requirementslib -docopt==0.6.2 - # via pipreqs edx-lint==5.3.6 # via -r requirements/quality.in -idna==3.6 - # via requests -isort==5.13.0 +isort==5.13.1 # via # -r requirements/quality.in # pylint @@ -47,27 +33,13 @@ mccabe==0.7.0 # via pylint pbr==6.0.0 # via stevedore -pep517==0.13.1 - # via requirementslib -pip-api==0.0.30 - # via isort -pipreqs==0.4.13 - # via isort platformdirs==4.1.0 - # via - # pylint - # requirementslib -plette[validation]==0.4.4 - # via requirementslib + # via pylint pycodestyle==2.11.1 # via -r requirements/quality.in -pydantic==2.5.2 - # via requirementslib -pydantic-core==2.14.5 - # via pydantic pydocstyle==6.3.0 # via -r requirements/quality.in -pylint==3.0.2 +pylint==3.0.3 # via # edx-lint # pylint-celery @@ -83,16 +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 -requests==2.31.0 - # via - # requirementslib - # yarg -requirementslib==3.0.0 - # via isort +pyyaml==6.0.1 + # via code-annotations six==1.16.0 # via edx-lint snowballstemmer==2.2.0 @@ -102,26 +66,10 @@ stevedore==5.1.0 text-unidecode==1.3 # via python-slugify tomli==2.0.1 - # via - # pep517 - # pylint + # via pylint tomlkit==0.12.3 - # via - # plette - # pylint - # requirementslib + # via pylint typing-extensions==4.9.0 # via - # annotated-types # astroid - # pydantic - # pydantic-core # pylint -urllib3==2.1.0 - # via requests -yarg==0.1.9 - # via pipreqs - -# The following packages are considered to be unsafe in a requirements file: -# pip -# setuptools diff --git a/requirements/test.txt b/requirements/test.txt index adb4e48f..2f67750b 100644 --- a/requirements/test.txt +++ b/requirements/test.txt @@ -84,7 +84,7 @@ packaging==23.2 # pytest pluggy==1.3.0 # via pytest -prompt-toolkit==3.0.41 +prompt-toolkit==3.0.42 # via # -r requirements/base.txt # click-repl @@ -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 From eab1b4c5854cb417890fbf214a050cc6b16ad16c Mon Sep 17 00:00:00 2001 From: Irtaza Akram Date: Thu, 14 Dec 2023 11:09:02 +0500 Subject: [PATCH 2/3] fix: replacement --- docs/conf.py | 1 + requirements/base.txt | 2 +- requirements/dev.txt | 4 ++-- requirements/doc.in | 1 + requirements/doc.txt | 43 ++++++++++++++++++++++++++++++++++++++-- requirements/quality.txt | 2 +- requirements/test.txt | 2 +- 7 files changed, 48 insertions(+), 7 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 8fb3b61c..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. diff --git a/requirements/base.txt b/requirements/base.txt index bc88b2d6..790a30fb 100644 --- a/requirements/base.txt +++ b/requirements/base.txt @@ -51,7 +51,7 @@ kombu==5.3.4 # via celery packaging==23.2 # via drf-yasg -prompt-toolkit==3.0.42 +prompt-toolkit==3.0.43 # via click-repl python-dateutil==2.8.2 # via celery diff --git a/requirements/dev.txt b/requirements/dev.txt index f806e390..3e2bd7a3 100644 --- a/requirements/dev.txt +++ b/requirements/dev.txt @@ -136,7 +136,7 @@ iniconfig==2.0.0 # via # -r requirements/test.txt # pytest -isort==5.13.1 +isort==5.13.2 # via # -r requirements/quality.txt # pylint @@ -193,7 +193,7 @@ pluggy==1.3.0 # tox polib==1.2.0 # via edx-i18n-tools -prompt-toolkit==3.0.42 +prompt-toolkit==3.0.43 # via # -r requirements/test.txt # click-repl diff --git a/requirements/doc.in b/requirements/doc.in index b32f3f10..a43793af 100644 --- a/requirements/doc.in +++ b/requirements/doc.in @@ -8,4 +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 +sphinxcontrib-openapi twine # Validates the generated long description for PyPI diff --git a/requirements/doc.txt b/requirements/doc.txt index f419cbbc..dbf063f0 100644 --- a/requirements/doc.txt +++ b/requirements/doc.txt @@ -16,6 +16,10 @@ asgiref==3.7.2 # via # -r requirements/base.txt # django +attrs==23.1.0 + # via + # jsonschema + # referencing babel==2.14.0 # via # pydata-sphinx-theme @@ -65,6 +69,8 @@ coreapi==2.3.3 # openapi-codec coreschema==0.0.4 # via coreapi +deepmerge==1.1.0 + # via sphinxcontrib-openapi django==3.2.23 # via # -c https://raw.githubusercontent.com/edx/edx-lint/master/edx_lint/files/common_constraints.txt @@ -90,6 +96,7 @@ docutils==0.19 # readme-renderer # restructuredtext-lint # sphinx + # sphinx-mdinclude drf-yasg==1.21.7 # via -r requirements/base.txt idna==3.6 @@ -102,7 +109,10 @@ importlib-metadata==7.0.0 # sphinx # twine importlib-resources==6.1.1 - # via keyring + # via + # jsonschema + # jsonschema-specifications + # keyring inflection==0.5.1 # via # -r requirements/base.txt @@ -115,6 +125,10 @@ jinja2==3.1.2 # via # coreschema # sphinx +jsonschema==4.20.0 + # via sphinxcontrib-openapi +jsonschema-specifications==2023.11.2 + # via jsonschema keyring==24.3.0 # via twine kombu==5.3.4 @@ -127,6 +141,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 @@ -141,9 +157,13 @@ packaging==23.2 # sphinx pbr==6.0.0 # via stevedore +picobox==4.0.0 + # via sphinxcontrib-openapi pkginfo==1.9.6 # via twine -prompt-toolkit==3.0.42 +pkgutil-resolve-name==1.3.10 + # via jsonschema +prompt-toolkit==3.0.43 # via # -r requirements/base.txt # click-repl @@ -157,6 +177,7 @@ pygments==2.17.2 # readme-renderer # rich # sphinx + # sphinx-mdinclude python-dateutil==2.8.2 # via # -r requirements/base.txt @@ -172,8 +193,13 @@ pyyaml==6.0.1 # via # -r requirements/base.txt # drf-yasg + # sphinxcontrib-openapi readme-renderer==42.0 # via twine +referencing==0.32.0 + # via + # jsonschema + # jsonschema-specifications requests==2.31.0 # via # coreapi @@ -188,6 +214,10 @@ rfc3986==2.0.0 # via twine rich==13.7.0 # via twine +rpds-py==0.13.2 + # via + # jsonschema + # referencing rules==3.3 # via -r requirements/doc.in simplejson==3.19.2 @@ -196,6 +226,7 @@ six==1.16.0 # via # -r requirements/base.txt # python-dateutil + # sphinxcontrib-httpdomain snowballstemmer==2.2.0 # via sphinx soupsieve==2.5 @@ -205,16 +236,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 diff --git a/requirements/quality.txt b/requirements/quality.txt index cc5003d8..7328eb12 100644 --- a/requirements/quality.txt +++ b/requirements/quality.txt @@ -21,7 +21,7 @@ dill==0.3.7 # via pylint edx-lint==5.3.6 # via -r requirements/quality.in -isort==5.13.1 +isort==5.13.2 # via # -r requirements/quality.in # pylint diff --git a/requirements/test.txt b/requirements/test.txt index 2f67750b..ed03e47b 100644 --- a/requirements/test.txt +++ b/requirements/test.txt @@ -84,7 +84,7 @@ packaging==23.2 # pytest pluggy==1.3.0 # via pytest -prompt-toolkit==3.0.42 +prompt-toolkit==3.0.43 # via # -r requirements/base.txt # click-repl From e52bbbc6d48a16ae83b868994f5ceebd04d1355d Mon Sep 17 00:00:00 2001 From: Irtaza Akram Date: Thu, 14 Dec 2023 11:24:43 +0500 Subject: [PATCH 3/3] fix: directive --- docs/readme.rst | 2 ++ 1 file changed, 2 insertions(+) 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