feat: manually generate autoapi docs

.github/workflows/ci_cd_pr.yml

@@ -117,8 +117,8 @@ jobs:
 
   doc:
     name: "Documentation build"
-    runs-on: ubuntu-latest
-    needs: [doc-style]
+    runs-on: [public-ubuntu-latest-16-cores]
+    # needs: [doc-style]
     steps:
       - name: "Checkout project"
         uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0

doc/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    = -j auto
+SPHINXOPTS    = -j 2
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build

doc/changelog/910.added.md

@@ -0,0 +1 @@
+Manually generate \`\`autoapi\`\` docs

doc/source/api.rst

@@ -0,0 +1,14 @@
+API reference
+=============
+
+This section describes PyDYNA's endpoints, their capabilities, and how
+to interact with them programmatically.
+
+.. toctree::
+   :titlesonly:
+   :maxdepth: 3
+
+   api/ansys/dyna/core/keyword
+   api/ansys/dyna/core/lib
+   api/ansys/dyna/core/run
+   api/ansys/dyna/core/solver

doc/source/autoapi/index.rst

@@ -8,10 +8,7 @@ to interact with them programmatically.
    :titlesonly:
    :maxdepth: 3
 
-   {% for page in pages %}
-   {% set length = autoapi_depth | int %}
-   {% if (page.top_level_object or page.name.split('.') | length == length) and page.display %}
-   <span class="nf nf-md-package"></span> {{ page.name }}<{{ page.include_path }}>
-   {% endif %}
-   {% endfor %}
-   <span class="nf nf-md-package"></span> Auto Keyword classes<../_autosummary/index>
+   api/ansys/dyna/core/keywords.html
+   api/ansys/dyna/core/lib.html
+   api/ansys/dyna/core/run.html
+   api/ansys/dyna/core/solver.html

doc/source/conf.py

@@ -31,7 +31,6 @@
     "sphinx_jinja",
     "pyvista.ext.plot_directive",
     "sphinx_design",
-    "ansys_sphinx_theme.extension.autoapi",
 ]
 
 # Intersphinx mapping
@@ -144,12 +143,8 @@
 
 # -- Declare the Jinja context -----------------------------------------------
 BUILD_API = True if os.environ.get("BUILD_API", "true") == "true" else False
-if not BUILD_API:
-    exclude_patterns.append("api")
-    html_theme_options.pop("ansys_sphinx_theme_autoapi")
-    extensions.remove("ansys_sphinx_theme.extension.autoapi")
 
-suppress_warnings = ["autoapi.python_import_resolution", "config.cache", "docutils"]
+suppress_warnings = ["autoapi.python_import_resolution", "config.cache", "docutils", "ref.python", "misc.highlighting_failure"]
 
 BUILD_AUTOKEYWORS_API = os.environ.get("BUILD_AUTOKEYWORS_API", "false").lower() == "true"
 if BUILD_AUTOKEYWORS_API:
@@ -194,6 +189,44 @@
     },
 }
 
+from sphinx.util import logging
+import pathlib
+import sys
+
+def run_autoapi(app):
+    """
+    Run the autoapi script to generate API documentation.
+
+    Parameters
+    ----------
+    app : sphinx.application.Sphinx
+        Sphinx application instance containing the all the doc build configuration.
+
+    """
+    logger = logging.getLogger(__name__)
+    logger.info("\nWriting reST files for API documentation...", color="green")
+
+    scripts_dir = pathlib.Path(app.srcdir).parent.parent / "scripts"
+    sys.path.append(str(scripts_dir.resolve()))
+
+    print(scripts_dir)
+
+    from autoapi import autodoc_extensions
+    autodoc_extensions()
+
+    logger.info("Done!\n")
+
+autodoc_default_options = {
+    #'members': 'var1, var2',
+    "member-order": "alphabetical",
+    #'special-members': '__init__',
+    "show-inheritance": True,
+    "undoc-members": True,
+    #'exclude-members': '__weakref__'
+}
+autodoc_class_signature = "separated"
+
+
 def skip_run_subpackage(app, what, name, obj, skip, options):
     """Skip specific members of the 'run' subpackage during documentation generation.
 
@@ -215,4 +248,10 @@ def skip_run_subpackage(app, what, name, obj, skip, options):
 
 def setup(sphinx):
     """Add custom extensions to Sphinx."""
-    sphinx.connect("autoapi-skip-member", skip_run_subpackage)
+    if BUILD_API:
+    # exclude_patterns.append("api")
+    # html_theme_options.pop("ansys_sphinx_theme_autoapi")
+    # extensions.remove("ansys_sphinx_theme.extension.autoapi")
+        sphinx.connect("builder-inited", run_autoapi)
+    # sphinx.connect("autoapi-skip-member", skip_run_subpackage)
+

doc/source/index.rst

@@ -24,7 +24,7 @@ PyDYNA documentation  |version|
 
       {% if build_api %}
       .. grid-item-card:: :fa:`wrench` API reference
-         :link: api/index
+         :link: api
          :link-type: doc
 
          Explore the API reference documentation for PyDYNA, including
@@ -67,7 +67,7 @@ PyDYNA documentation  |version|
        getting-started
        user-guide/index
        {% if build_api %}
-       api/index
+       api
        {% endif %}
        {% if build_examples %}
        examples/index

pyproject.toml

@@ -84,17 +84,12 @@ doc = [
     "ansys-sphinx-theme==1.6.1",
     "pypandoc==1.15",
     "nbsphinx==0.9.6",
-
-
-
-
     "ipywidgets==8.1.7",
     "joblib==1.5.2",
     "scikit-learn==1.7.2",
     "ipython==8.37.0",
     "jupyterlab==4.4.7",
     "sphinx-jinja==2.0.2",
-    "sphinx-autoapi==3.6.0",
     "pyvista==0.46.3",
 ]