Update api docs to render docstrings correctly

Author: melund

anypytools/abcutils.py

@@ -139,13 +139,13 @@ def execute_anybodycon(
 
     Parameters
     ----------
-    macro : list of str
+    macro : list[str]
         List of macros strings to pass to the AnyBody Console Application
-    logfile : file like object, optional
+    logfile : typing.TextIO, optional
         An open file like object to write to pipe the output of AnyBody
         into. (Defaults to None, in which case it will use sys.stdout)
     anybodycon_path : str, optional
-        Path to the AnyBodyConsole application. Default to None, in which
+        Path to the AnyBodyConsole applibcation. Default to None, in which
         case the default installed AnyBody installation will be looked up
         in the Windows registry.
     timeout : int, optional
@@ -165,15 +165,15 @@ def execute_anybodycon(
     interactive_mode : bool, optional
         If set to True, the AnyBody Console application will be started in iteractive
         mode, and will not shutdown autmaticaly after running the macro. (Defaults to False)
-    debug_mode : int
+    debug_mode : int, optional
         The AMS debug mode to use. Defaults to 0 which is disabled. 1 correspond to
         crashdump enabled
     folder :
         the folder in which AnyBody is executed
 
     Returns
     -------
-    int
+    error_code : int
         The return code from the AnyBody Console application.
 
     """
@@ -497,7 +497,7 @@ class AnyPyProcess(object):
         String which will be prefixed to the generated log files. This can be used
         to assign a more meaningfull name to a batch of logfiles.
         (Defaults to None)
-    python_env : pathlike, optional
+    python_env : str, optional
         Path to a python environment/installation that the AnyBody Modeling System
         should use for Python Hooks. This will added the ``PYTHONHOME`` environment variable and
         prepended to the ``PATH`` before starting the AnyBody Console application.
@@ -746,10 +746,10 @@ def start_macro(
 
         Parameters
         ----------
-        macrolist : list of macrocommands, optional
+        macrolist : list, optional
             List of anyscript macro commands. This may also be obmitted in
             which case the previous macros will be re-run.
-        folderlist : list of str, optional
+        folderlist : list[str], optional
             List of folders in which to excute the macro commands. If `None` the
             current working directory is used. This may also be a list of
             tuples to specify a name to appear in the output

anypytools/macroutils.py

@@ -79,7 +79,7 @@ def get_macro(self, index, **kwarg):
 
         Returns
         -------
-        string
+        str
             A string with the AnyScript macro
 
         """
@@ -139,9 +139,9 @@ class SetValue(MacroCommand):
 
     Parameters
     ----------
-    var : string
+    var : str
         An AnyScript variable.
-    value : number or list of number
+    value : float | list[float]
         A value or list of values to assign to the AnyScript variable.
 
     Examples
@@ -232,13 +232,13 @@ def _format_macro(self, val):
 class SetValue_random(SetValue):
     """Create a 'Set Value' macro command from a distribution.
 
-    The value is connected to a distibution in scipy.stats.distributions.
+    The value is connected to a distibution in ``scipy.stats.distributions``.
 
     Parameters
     ----------
     var : str
         An AnyScript variable.
-    frozen_distribution : <scipy.stats.distributions.rv_frozen>
+    frozen_distribution :
         A frozen distribution from scipy.stats.distributions
     default_lower_tail_probability : float
         The lower tail probability of the default value. Defaults to 0.5 which
@@ -430,11 +430,11 @@ class ExtendOutput(MacroCommand):
     ----------
     var_name : str
         Name of the variable in output.
-    value : any
+    value : int | float | str | np.ndarray
         The value to add to the output.
 
-    Examples:
-    ---------
+    Examples
+    --------
     >>> ExtendOutput('MyVar', 23.5)
     print MyVar = 23.5;
 
@@ -719,8 +719,7 @@ class AnyMacro(MutableSequence):
     >>> mg = AnyMacro(number_of_macros = 22)
     >>> mg.append( Load('c:/MyModel/model.main.any', defs = {}, paths = {} ) )
     >>> mg.append( SetValue('Main.myvar', 12.3)  )
-    >>> mg.extend( [RunOperation('Main.Study.Kinematics'),
-                     Dump('Main.Study.Output.MyVar') ] )
+    >>> mg.extend( [RunOperation('Main.Study.Kinematics'), Dump('Main.Study.Output.MyVar') ] )
     >>> mg
     [['load "c:/MyModel/model.main.any"',
       'classoperation Main.myvar "Set Value" --value="12.3"',

anypytools/tools.py

@@ -48,7 +48,7 @@
     "anybodycon_version",
     "AMSVersion",
     "parse_anybodycon_output",
-    "wraptext"
+    "wraptext",
 ]
 
 

docs/api.md

@@ -3,9 +3,8 @@
 
 :::{toctree}
 :maxdepth: 2
-:hidden:
 
 pytest-plugin
-apidocs/index
+api/index
 
 :::

docs/conf.py

@@ -5,11 +5,53 @@
 from anypytools import __version__ as ANYPYTOOLS_VERSION
 
 # load extensions
-extensions = ["myst_nb", "autodoc2", "sphinx.ext.intersphinx", "sphinx.ext.napoleon", "sphinx_design"
+extensions = [
+    "myst_nb",
+    "autodoc2",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx_design"
+]
+
+
+autodoc2_packages = [
+ "../anypytools",
+]
 
+autodoc2_output_dir = "api"
+autodoc2_render_plugin = "rst"
 
+autodoc2_module_all_regexes = [
+    r"anypytools\..*",
 ]
 
+
+nitpick_ignore = [
+    ('py:class', 'optional'),
+    ('py:class', 'np.ndarray'),
+    ]
+
+
+# autodoc2_render_plugin = "myst"
+
+# autodoc2_hidden_objects = ["dunder", "inherited"]
+autodoc2_replace_annotations = [
+    ("re.Pattern", "typing.Pattern"),
+    ("markdown_it.MarkdownIt", "markdown_it.main.MarkdownIt"),
+]
+autodoc2_replace_bases = [
+    ("sphinx.directives.SphinxDirective", "sphinx.util.docutils.SphinxDirective"),
+]
+
+napoleon_use_ivar = True
+
+# Napoleon settings for NumPy-style
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_admonition_for_notes = False
+
+
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
     "sphinx": ("https://www.sphinx-doc.org/en/master", None),
@@ -106,29 +148,6 @@
     "doc_path": "docs",
 }
 
-
-autodoc2_packages = [
-    {
-        "path": "../anypytools",
-        # "exclude_files": ["_docs.py"],
-    }
-]
-
-autodoc2_module_all_regexes = [
-    r"anypytools\..*",
-]
-
-
-autodoc2_render_plugin = "myst"
-
-# autodoc2_hidden_objects = ["dunder", "inherited"]
-autodoc2_replace_annotations = [
-    ("re.Pattern", "typing.Pattern"),
-    ("markdown_it.MarkdownIt", "markdown_it.main.MarkdownIt"),
-]
-autodoc2_replace_bases = [
-    ("sphinx.directives.SphinxDirective", "sphinx.util.docutils.SphinxDirective"),
-]
 # autodoc2_docstring_parser_regexes = [
 #     ("myst_parser", "myst"),
 #     (r"myst_parser\.setup", "myst"),

docs/index.md

@@ -75,7 +75,7 @@ User guide <user-guide/index>
 ## API Documenation
 
 * [PyTest plugin for testing AnyBody models](pytest-plugin)
-* [API reference](apidocs/index)
+* [API reference](api/index)
 
 :::{toctree}
 :maxdepth: 2

docs/pytest-plugin.md

@@ -7,8 +7,8 @@ collect and run AnyScript files with a `test_` prefix (e.g.
 `Main.RunTest` operation if it exists. If the models produce error while
 loading and running, the framework considers it a failed test.
 
-.. autodoc2-summary::
-    :renderer: myst
+:::{autodoc2-summary}
+:renderer: myst
 
     anypytools.pytest_plugin
-
+:::

pixi.lock

@@ -97,7 +97,7 @@ astroid = ">=2.7,<4"
 sphinxcontrib-napoleon = ">=0.7,<0.8"
 
 [feature.docs.pypi-dependencies]
-sphinx-autodoc2 = { git = "https://github.com/AnyBody-Research-Group/sphinx-autodoc2", branch = "main" }
+sphinx-autodoc2 = { git = "https://github.com/AnyBody-Research-Group/sphinx-autodoc2", rev = "215f04e72efc7294a0c93de4f038b9a1aa806e8f" }
 
 [feature.docs.tasks]
 build-docs = {cmd="sphinx-build -nW --keep-going -b html docs/ docs/_build/html"}