From 68a626a93895a6e4fbdaf4841e481fb09cb7c50a Mon Sep 17 00:00:00 2001 From: Irtaza Akram <51848298+irtazaakram@users.noreply.github.com> Date: Mon, 18 Nov 2024 10:16:09 +0500 Subject: [PATCH] fix: replace autodoc with autoapi (#35846) --- docs/conf.py | 20 +++++++++++-------- .../djangoapps/user_api/accounts/utils.py | 10 +++++----- requirements/constraints.txt | 1 + requirements/edx/development.txt | 9 +++++++++ requirements/edx/doc.in | 1 + requirements/edx/doc.txt | 15 +++++++++++++- requirements/edx/testing.txt | 1 + 7 files changed, 43 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7352195cbb11..604ca3755429 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -55,7 +55,6 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.doctest', 'sphinx.ext.graphviz', @@ -68,6 +67,18 @@ 'sphinx_design', 'code_annotations.contrib.sphinx.extensions.featuretoggles', 'code_annotations.contrib.sphinx.extensions.settings', + 'autoapi.extension', +] + +autoapi_type = 'python' +autoapi_dirs = ['../lms', '../openedx'] + +autoapi_ignore = [ + '*/migrations/*', + '*/tests/*', + '*.pyc', + '__init__.py', + '**/xblock_serializer/data.py', ] # Rediraffe related settings. @@ -277,13 +288,6 @@ 'django': ('https://docs.djangoproject.com/en/1.11/', 'https://docs.djangoproject.com/en/1.11/_objects/'), } -# Mock out these external modules during code import to avoid errors -autodoc_mock_imports = [ - 'MySQLdb', - 'django_mysql', - 'pymongo', -] - # Start building a map of the directories relative to the repository root to # run sphinx-apidoc against and the directories under "docs" in which to store # the generated *.rst files diff --git a/openedx/core/djangoapps/user_api/accounts/utils.py b/openedx/core/djangoapps/user_api/accounts/utils.py index 3cc03c02ed5d..826dbd42cd13 100644 --- a/openedx/core/djangoapps/user_api/accounts/utils.py +++ b/openedx/core/djangoapps/user_api/accounts/utils.py @@ -51,11 +51,11 @@ def format_social_link(platform_name, new_social_link): """ Given a user's social link, returns a safe absolute url for the social link. - Returns the following based on the provided new_social_link: - 1) Given an empty string, returns '' - 1) Given a valid username, return 'https://www.[platform_name_base][username]' - 2) Given a valid URL, return 'https://www.[platform_name_base][username]' - 3) Given anything unparseable, returns None + Returns: + - An empty string if `new_social_link` is empty. + - A formatted URL if `new_social_link` is a username. + - Returns `new_social_link` if it is a valid URL. + - None for unparseable inputs. """ # Blank social links should return '' or None as was passed in. if not new_social_link: diff --git a/requirements/constraints.txt b/requirements/constraints.txt index 426e7e67ece4..48b74cac6a10 100644 --- a/requirements/constraints.txt +++ b/requirements/constraints.txt @@ -156,6 +156,7 @@ pycodestyle<2.9.0 # Date: 2021-07-12 # Issue for unpinning: https://github.com/openedx/edx-platform/issues/33560 pylint<2.16.0 # greater version failing quality test. Fix them in seperate ticket. +astroid<2.14.0 # Date: 2021-08-25 # At the time of writing this comment, we do not know whether py2neo>=2022 diff --git a/requirements/edx/development.txt b/requirements/edx/development.txt index b8812b726156..94b4f14e18e0 100644 --- a/requirements/edx/development.txt +++ b/requirements/edx/development.txt @@ -83,9 +83,12 @@ asn1crypto==1.5.1 # snowflake-connector-python astroid==2.13.5 # via + # -c requirements/edx/../constraints.txt + # -r requirements/edx/doc.txt # -r requirements/edx/testing.txt # pylint # pylint-celery + # sphinx-autoapi attrs==24.2.0 # via # -r requirements/edx/doc.txt @@ -1103,6 +1106,7 @@ jinja2==3.1.4 # code-annotations # diff-cover # sphinx + # sphinx-autoapi jmespath==1.0.1 # via # -r requirements/edx/doc.txt @@ -1166,6 +1170,7 @@ lazy==1.6 # xblock lazy-object-proxy==1.10.0 # via + # -r requirements/edx/doc.txt # -r requirements/edx/testing.txt # astroid libsass==0.10.0 @@ -1799,6 +1804,7 @@ pyyaml==6.0.2 # edx-django-release-util # edx-i18n-tools # jsondiff + # sphinx-autoapi # sphinxcontrib-openapi # xblock random2==1.0.2 @@ -1999,6 +2005,7 @@ sphinx==8.1.3 # via # -r requirements/edx/doc.txt # pydata-sphinx-theme + # sphinx-autoapi # sphinx-book-theme # sphinx-design # sphinx-mdinclude @@ -2006,6 +2013,8 @@ sphinx==8.1.3 # sphinxcontrib-httpdomain # sphinxcontrib-openapi # sphinxext-rediraffe +sphinx-autoapi==3.3.3 + # via -r requirements/edx/doc.txt sphinx-book-theme==1.1.3 # via -r requirements/edx/doc.txt sphinx-design==0.6.1 diff --git a/requirements/edx/doc.in b/requirements/edx/doc.in index 013bafc42ec0..78afbf9d6bd0 100644 --- a/requirements/edx/doc.in +++ b/requirements/edx/doc.in @@ -10,3 +10,4 @@ sphinx-design # provides various responsive web-components sphinxcontrib-openapi[markdown] # Be able to render openapi schema in a sphinx project sphinxext-rediraffe # Quickly and easily redirect when we move pages around. sphinx-reredirects # Redirect from a sphinx project out to other places on the web including other sphinx projects +sphinx-autoapi diff --git a/requirements/edx/doc.txt b/requirements/edx/doc.txt index e4ece3a1f0f3..96ec726460c8 100644 --- a/requirements/edx/doc.txt +++ b/requirements/edx/doc.txt @@ -57,6 +57,10 @@ asn1crypto==1.5.1 # via # -r requirements/edx/base.txt # snowflake-connector-python +astroid==2.13.5 + # via + # -c requirements/edx/../constraints.txt + # sphinx-autoapi attrs==24.2.0 # via # -r requirements/edx/base.txt @@ -790,6 +794,7 @@ jinja2==3.1.4 # -r requirements/edx/base.txt # code-annotations # sphinx + # sphinx-autoapi jmespath==1.0.1 # via # -r requirements/edx/base.txt @@ -840,6 +845,8 @@ lazy==1.6 # lti-consumer-xblock # ora2 # xblock +lazy-object-proxy==1.10.0 + # via astroid libsass==0.10.0 # via # -c requirements/edx/../constraints.txt @@ -1247,6 +1254,7 @@ pyyaml==6.0.2 # edx-django-release-util # edx-i18n-tools # jsondiff + # sphinx-autoapi # sphinxcontrib-openapi # xblock random2==1.0.2 @@ -1405,6 +1413,7 @@ sphinx==8.1.3 # via # -r requirements/edx/doc.in # pydata-sphinx-theme + # sphinx-autoapi # sphinx-book-theme # sphinx-design # sphinx-mdinclude @@ -1412,6 +1421,8 @@ sphinx==8.1.3 # sphinxcontrib-httpdomain # sphinxcontrib-openapi # sphinxext-rediraffe +sphinx-autoapi==3.3.3 + # via -r requirements/edx/doc.in sphinx-book-theme==1.1.3 # via -r requirements/edx/doc.in sphinx-design==0.6.1 @@ -1556,7 +1567,9 @@ webob==1.8.9 # -r requirements/edx/base.txt # xblock wrapt==1.16.0 - # via -r requirements/edx/base.txt + # via + # -r requirements/edx/base.txt + # astroid xblock[django]==5.1.0 # via # -r requirements/edx/base.txt diff --git a/requirements/edx/testing.txt b/requirements/edx/testing.txt index c56636395bfd..b344dc9f5a22 100644 --- a/requirements/edx/testing.txt +++ b/requirements/edx/testing.txt @@ -57,6 +57,7 @@ asn1crypto==1.5.1 # snowflake-connector-python astroid==2.13.5 # via + # -c requirements/edx/../constraints.txt # pylint # pylint-celery attrs==24.2.0