fix: failing Docs Builds

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

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:

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

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,13 +2005,16 @@ sphinx==8.1.3
     # via
     #   -r requirements/edx/doc.txt
     #   pydata-sphinx-theme
+    #   sphinx-autoapi
     #   sphinx-book-theme
     #   sphinx-design
     #   sphinx-mdinclude
     #   sphinx-reredirects
     #   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

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

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,13 +1413,16 @@ sphinx==8.1.3
     # via
     #   -r requirements/edx/doc.in
     #   pydata-sphinx-theme
+    #   sphinx-autoapi
     #   sphinx-book-theme
     #   sphinx-design
     #   sphinx-mdinclude
     #   sphinx-reredirects
     #   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

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