fix: hide some implementation from run package and migrate to theme autoapi (#797)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: pyansys-ci-bot <92810346+pyansys-ci-bot@users.noreply.github.com>

Author: 3 people

.gitignore

@@ -164,4 +164,4 @@ cython_debug/
 # Ignore rendered examples
 doc/source/examples/
 doc/source/API/_autosummary/
-doc/source/autoapi
+doc/source/api

doc/Makefile

@@ -7,6 +7,7 @@ SPHINXOPTS    = -j auto
 SPHINXBUILD   = sphinx-build
 SOURCEDIR     = source
 BUILDDIR      = _build
+APIDIR       = api
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -22,7 +23,7 @@ help:
 clean:
 	rm -rf $(BUILDDIR)/*
 	rm -rf source/examples/gallery_examples
-	find . -type d -name "_autosummary" -exec rm -rf {} +
+	find . -type d -name $(APIDIR) -exec rm -rf {} +
 
 pdf:
 	@$(SPHINXBUILD) -M latex "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/changelog/797.fixed.md

@@ -0,0 +1 @@
+hide some implementation from run package and migrate to theme autoapi

doc/make.bat

@@ -9,6 +9,7 @@ if "%SPHINXBUILD%" == "" (
 )
 set SOURCEDIR=source
 set BUILDDIR=_build
+set APIDIR=source\api
 
 if "%1" == "" goto help
 if "%1" == "clean" goto clean
@@ -32,7 +33,7 @@ goto end
 
 :clean
 rmdir /s /q %BUILDDIR% > /NUL 2>&1 
-for /d /r %SOURCEDIR% %%d in (_autosummary) do @if exist "%%d" rmdir /s /q "%%d"
+rmdir /s /q %APIDIR% > /NUL 2>&1
 goto end
 
 :help

doc/source/_autoapi_templates/index.rst

@@ -18,7 +18,7 @@
 copyright = f"(c) {datetime.datetime.now().year} ANSYS, Inc. All rights reserved"
 author = 'ANSYS Inc.'
 release = version = __version__
-cname = os.getenv("DOCUMENTATION_CNAME", default="nocname.com")
+cname = os.getenv("DOCUMENTATION_CNAME", default="dyna.docs.pyansys.com")
 
 # Sphinx extensions
 extensions = [
@@ -31,6 +31,7 @@
     "sphinx_jinja",
     "pyvista.ext.plot_directive",
     "sphinx_design",
+    "ansys_sphinx_theme.extension.autoapi",
 ]
 
 # Intersphinx mapping
@@ -126,6 +127,13 @@
     ],
     "collapse_navigation": True,
     "use_edit_page_button": True,
+    "ansys_sphinx_theme_autoapi": {
+        "project": project,
+        "ignore": [
+            "*core/keywords/keyword_classes/auto*",
+        ],
+        "output": "api",
+    },
 }
 
 # static path
@@ -134,25 +142,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("_autoapi_templates")
-else:
-    # Configuration for Sphinx autoapi
-    extensions.append("autoapi.extension")
-    autoapi_dirs = ["../../src/ansys"]
-    autoapi_ignore = ["*core/keywords/keyword_classes/auto*"]
-    autoapi_type = "python"
-    autoapi_options = [
-        "members",
-        "undoc-members",
-        "show-inheritance",
-        "show-module-summary",
-        "special-members",
-    ]
-    autoapi_template_dir = "_autoapi_templates"
-    suppress_warnings = ["autoapi.python_import_resolution", "config.cache"]
-    exclude_patterns.append("_autoapi_templates/index.rst")
-    autoapi_python_use_implicit_namespaces = True
+
+suppress_warnings = ["autoapi.python_import_resolution", "config.cache"]
 
 BUILD_EXAMPLES = (
     True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
@@ -194,3 +185,26 @@
         "build_examples": BUILD_EXAMPLES,
     },
 }
+
+
+def skip_run_subpackage(app, what, name, obj, skip, options):
+    """Skip specific members of the 'run' subpackage during documentation generation.
+
+    This function skips:
+    - All modules under 'ansys.dyna.core.run' except 'local_solver' and 'options'.
+    - Within 'local_solver', skips all members except the 'run_dyna' function.
+    """
+    
+    
+    if name.startswith("ansys.dyna.core.run.") and not (name.startswith("ansys.dyna.core.run.local_solver") or name.startswith("ansys.dyna.core.run.options")):
+            skip = True
+
+    if name.startswith("ansys.dyna.core.run.local_solver"):
+        if what == "function" and name!= "ansys.dyna.core.run.local_solver.run_dyna":
+            skip = True
+
+    return skip
+
+def setup(sphinx):
+    """Add custom extensions to Sphinx."""
+    sphinx.connect("autoapi-skip-member", skip_run_subpackage)

doc/source/conf.py

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

doc/source/index.rst

@@ -80,7 +80,7 @@ doc = [
     "sphinx-copybutton==0.5.2",
     "sphinx-gallery==0.19.0",
     "sphinx-autodoc-typehints==3.1.0",
-    "ansys-sphinx-theme==1.3.2",
+    "ansys-sphinx-theme==1.4.2",
     "pypandoc==1.15",
     "nbsphinx==0.9.6",
     "ipywidgets==8.1.6",

pyproject.toml

@@ -252,10 +252,10 @@ def _expand_helper(self, search_paths: typing.List[str], recurse: bool) -> typin
     def expand(self, cwd=None, recurse=True):
         """Get a new deck that is flattened copy of `self`.
 
-        A flattened deck is one where the *INCLUDE keywords are replaced
+        A flattened deck is one where the ``*INCLUDE`` keywords are replaced
         by the contents of the file that is included.
         `cwd` is a working directory used to resolve the filename
-        If `recurse` is true, *INCLUDE keywords within included decks
+        If `recurse` is true, ``*INCLUDE`` keywords within included decks
         are expanded, recursively.
         """
         cwd = cwd or os.getcwd()
@@ -424,7 +424,7 @@ def get_kwds_by_type(self, str_type: str) -> typing.Iterator[KeywordBase]:
 
         Examples
         --------
-        Get all *SECTION_* keywords in the deck.
+        Get all ``*SECTION_*`` keywords in the deck.
 
         >>>deck.get_kwds_by_type("SECTION")
         """
@@ -446,7 +446,7 @@ def get_kwds_by_full_type(self, str_type: str, str_subtype: str) -> typing.Itera
 
         Examples
         --------
-        Get all *SECTION_SHELL keyword instances in the deck.
+        Get all ``*SECTION_SHELL`` keyword instances in the deck.
 
         >>>deck.get_kwds_by_full_type("SECTION", "SHELL")
         """
@@ -485,10 +485,11 @@ def get(self, **kwargs) -> typing.List[KeywordBase]:
 
         Parameters
         ----------
-        :Keyword Arguments:
-        * *type* (``str``) --
+        - *kwargs* (``dict``) --
+            Keyword arguments.
+            * *type* (``str``) --
             The type of keyword to get. For example, "SECTION" returns all section keywords.
-        * *filter* (``callable``) --
+            * *filter* (``callable``) --
             The filter to apply to the result. Only keywords which pass the filter will be returned.
 
         """

src/ansys/dyna/core/lib/deck.py

@@ -127,9 +127,11 @@ def _contract_data(spec: typing.List[tuple], data: typing.List) -> typing.Iterab
 def load_dataline(spec: typing.List[tuple], line_data: str, parameter_set: ParameterSet = None) -> typing.List:
     """loads a keyword card line with fixed column offsets and width from string
     spec: list of tuples representing the (offset, width, type) of each field
-          type can be a Flag which represents the True and False value
+    type can be a Flag which represents the True and False value
     line_data: string with keyword data
-    example:
+
+    Example
+    -------
     >>> load_dataline([(0,10, int),(10,10, str)], '         1     hello')
     (1, 'hello')
     """