Update and simplify documentation (#128)

* Update documenation to new theme

* Support stange output variable names

* Refactor `to_dataframe` method to include task information option and update documentation

* Update user guide, and simply as many examples as possible.

* black formatting

* Update dependencies

* Update user guide to clarify installation and setup instructions

* Expose `wraptext` function in the module's public API

* Update api docs to render docstrings correctly

Author: melund

.gitignore

@@ -21,3 +21,5 @@ Tests/anytest_output
 # pixi environments
 .pixi
 
+docs/apidocs/*
+docs/user-guide/*.txt

CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## v1.19.0
 
+**Changed:**
+*  The `results.to_dataframe()` no longer returns the special `task_*` (meta data) in the output columns. 
+   To get the extra task info use `results.to_dataframe(*, include_task_info=True)`
+*  The documentation page updated.
+
 **Added:**
 * New `macro_commands.ExtendOutput()` helper macro that can add arbitrary values 
   to the results output. This allows adding values that don't need to exist as 
@@ -230,7 +235,7 @@ just treated as NaN.
 - Fixed issue which would cauase macros to execute twice when running the GUI version of AnyBody. 
 
 **Added:**
-- Added a `interactive_mode` argument to the {class}`AnyPyProcess <anypytools.AnPyProcess>` class. Setting this argument will automaticially lauch the GUI version
+- Added a `interactive_mode` argument to the {class}`AnyPyProcess <anypytools.abcutils.AnyPyProcess>` class. Setting this argument will automaticially lauch the GUI version
 of AnyBody with the macro commands. Futher it will not automatically exit AnyBody once the macro commands has finished. This must be done manually by the user. 
 
 
@@ -546,15 +551,15 @@ happend because empty folders (represented by "...") would become the python eli
 
 **Fixed:**
 
-- Fix regression in for {class}`AnyPyTools.macro_comands.SetValue_random` which caused a
+- Fix regression in for {py:class}`SetValue_random <anypytools.macroutils.SetValue_random>` which caused a
   crash when generating macros.
 
 ## v0.12
 
 **Fixed:**
 
 - Missing newlines in error output from pytest plugin.
-- Fix a problem where the `ignore_errors` argument to {class}`AnyPyProcess()` could
+- Fix a problem where the `ignore_errors` argument to {class}`anypytools.abcutils.AnyPyProcess` could
   not filter warnings when they were considered as errors with the `fatal_warnings`
   arguments.
 
@@ -578,7 +583,7 @@ happend because empty folders (represented by "...") would become the python eli
 **New:**
 
 - Added option to the set the priority of the macro operations.
-  The option is an argument to {class}`AnyPyProcess()`.
+  The option is an argument to {class}`AnyPyProcess <anypytools.abcutils.AnyPyProcess>`.
 
   ```python
   from anypytools import IDLE_PRIORITY_CLASS
@@ -593,7 +598,7 @@ happend because empty folders (represented by "...") would become the python eli
   - `NORMAL_PRIORITY_CLASS`
   - `ABOVE_NORMAL_PRIORITY_CLASS`.
 
-- Added argument `fatal_warnings` to {class}`AnyPyProcess()` which
+- Added argument `fatal_warnings` to {class}`AnyPyProcess <anypytools.abcutils.AnyPyProcess>` which
   treat warnings as errors when running macros.
 
   ```python

README.md

@@ -27,7 +27,6 @@ If you use the library for publications please **cite as:**
 ```bash
 pixi init
 pixi add anypytools
-pixi install
 ```
 
 This will install a virtual environment with python, anypytools and all
@@ -60,6 +59,4 @@ Please see the [Jupyter Notebook based tutorial], or check the the following for
 <img src="docs/_static/relax.png" alt="Don't panic" height="100px">
 
 
-[anaconda python distribution]: https://store.continuum.io/cshop/anaconda/
 [anybody modeling system (ams)]: http://www.anybodytech.com
-[jupyter notebook based tutorial]: http://nbviewer.jupyter.org/github/AnyBody-Research-Group/AnyPyTools/blob/master/docs/Tutorial/00_AnyPyTools_tutorial.ipynb

anypytools/abcutils.py

@@ -53,6 +53,12 @@
     winepath,
 )
 
+__all__ = [
+    "execute_anybodycon",
+    "AnyPyProcess",
+    "Task",
+]
+
 if ON_WINDOWS:
     from .jobpopen import JobPopen as Popen
     from subprocess import CREATE_NEW_PROCESS_GROUP
@@ -107,7 +113,7 @@ def stop_all(self):
 atexit.register(_subprocess_container.stop_all)
 
 
-def progress_print(progress, content):
+def _progress_print(progress, content):
     previous = progress.console.is_jupyter
     progress.console.is_jupyter = False
     progress.console.print(content)
@@ -133,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
@@ -159,14 +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
+    folder :
+        the folder in which AnyBody is executed
 
     Returns
     -------
-    int
+    error_code : int
         The return code from the AnyBody Console application.
 
     """
@@ -314,7 +321,7 @@ def execute_anybodycon(
     return retcode
 
 
-class _Task(object):
+class Task(object):
     """Class for storing processing jobs.
 
     Attributes:
@@ -418,7 +425,7 @@ def is_valid(output_elem):
         return all(k in output_elem for k in keys)
 
 
-def tasklist_summery(tasklist: List[_Task]) -> str:
+def _tasklist_summery(tasklist: List[Task]) -> str:
     out = ""
     unfinished_tasks = [t for t in tasklist if t.processtime <= 0]
     failed_tasks = [t for t in tasklist if t.has_error() and t.processtime > 0]
@@ -431,7 +438,7 @@ def tasklist_summery(tasklist: List[_Task]) -> str:
     return out
 
 
-def task_summery(task: _Task) -> str:
+def _task_summery(task: Task) -> str:
     if task.has_error():
         status = "Failed"
     elif task.processtime == 0:
@@ -490,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.
@@ -739,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
@@ -822,7 +829,7 @@ def start_macro(
                     "to process"
                 )
         elif isinstance(macrolist[0], collections.abc.Mapping):
-            tasklist = list(_Task.from_output_list(macrolist))
+            tasklist = list(Task.from_output_list(macrolist))
         elif isinstance(macrolist[0], list):
             arg_hash = format(
                 abs(make_hash([macrolist, folderlist, search_subdirs, logfile])), "x"
@@ -832,7 +839,7 @@ def start_macro(
             else:
                 self.cached_arg_hash = arg_hash
                 tasklist = list(
-                    _Task.from_macrofolderlist(macrolist, folderlist, logfile)
+                    Task.from_macrofolderlist(macrolist, folderlist, logfile)
                 )
         else:
             raise ValueError("Nothing to process for " + str(macrolist))
@@ -850,15 +857,15 @@ def start_macro(
             try:
                 for task in self._schedule_processes(tasklist):
                     if task.has_error() and not self.silent:
-                        progress_print(progress, task_summery(task))
+                        _progress_print(progress, _task_summery(task))
                         progress.update(task_progress, style="red", refresh=True)
                     progress.update(task_progress, advance=1, refresh=True)
             except KeyboardInterrupt:
-                progress_print(progress, "[red]KeyboardInterrupt: User aborted[/red]")
+                _progress_print(progress, "[red]KeyboardInterrupt: User aborted[/red]")
             finally:
                 _subprocess_container.stop_all()
                 if not self.silent:
-                    progress_print(progress, tasklist_summery(tasklist))
+                    _progress_print(progress, _tasklist_summery(tasklist))
 
         self.cleanup_logfiles(tasklist)
         # Cache the processed tasklist for restarting later
@@ -940,9 +947,7 @@ def _worker(self, task, task_queue):
                 task.logfile = ""
             task_queue.put(task)
 
-    def _schedule_processes(
-        self, tasklist: List[_Task]
-    ) -> Generator[_Task, None, None]:
+    def _schedule_processes(self, tasklist: List[Task]) -> Generator[Task, None, None]:
         # Make a shallow copy of the task list,
         # so we don't mess with the callers list.
         tasklist = copy.copy(tasklist)

anypytools/h5py_wrapper.py

@@ -10,6 +10,8 @@
 
 logger = logging.getLogger("abt.anypytools")
 
+__all__ = ["File", "Group", "Dataset"]
+
 
 def _follow_reftarget(elem):
     completename = elem.attrs["CompleteName"]

anypytools/jobpopen.py

@@ -15,6 +15,8 @@
 import win32process
 import pywintypes
 
+__all__ = ["JobPopen"]
+
 
 class JobPopen(Popen):
     """Start a process in a new Win32 job object.

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;
 
@@ -457,7 +457,16 @@ def get_macro(self, index, **kwarg):
             val_str = f"'{self.value}'"
         else:
             val_str = str(self.value)
-        return f'print "{self.var_name} = {val_str};"'
+
+        cmd = ""
+        if self.var_name.isidentifier():
+            name = self.var_name
+        else:
+            cmd += f'print "#### ANYPYTOOLS RENAME OUTPUT: {self.var_name}"\n'
+            name = "DUMMY"
+
+        cmd += f'print "{name} = {val_str};"'
+        return cmd
 
 
 class SaveDesign(MacroCommand):
@@ -710,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/pytest_plugin.py

@@ -34,22 +34,18 @@
     get_bm_constants,
     anybodycon_version,
     find_ammr_path,
-    get_tag,
     get_ammr_version,
     winepath,
     wraptext,
     AMSVersion,
 )
 
-
-@contextlib.contextmanager
-def cwd(path):
-    oldpwd = os.getcwd()
-    os.chdir(path)
-    try:
-        yield
-    finally:
-        os.chdir(oldpwd)
+__all__ = [
+    "AnyTestFile",
+    "AnyTestItem",
+    "AnyException",
+    "AnyTestSession",
+]
 
 
 DEFAULT_ANYTEST_OUTPUT = Path.cwd() / "anytest-output"
@@ -58,7 +54,7 @@ def cwd(path):
 RUN_TEST_TIME_VARIABLE = "Main.RunTest.RunDurationCPUThread"
 
 
-def load_duration_supported():
+def _is_load_duration_supported():
     return AMSVersion.from_string(pytest.anytest.ams_version) >= (7, 5, 0, 10759)
 
 
@@ -314,7 +310,7 @@ def __init__(self, name, id, parent, any_defs, any_paths, **kwargs):
             macro_commands.Load(mainfile, self.any_defs, self.any_paths),
         ]
 
-        if load_duration_supported():
+        if _is_load_duration_supported():
             self.macro += [
                 macro_commands.Dump(LOAD_TIME_VARIABLE),
             ]
@@ -348,7 +344,7 @@ def __init__(self, name, id, parent, any_defs, any_paths, **kwargs):
         if not self.config.getoption("--only-load"):
             self.macro += [macro_commands.RunOperation("Main.RunTest")]
 
-        if load_duration_supported():
+        if _is_load_duration_supported():
             self.macro += [
                 macro_commands.Dump(RUN_TEST_TIME_VARIABLE),
             ]
@@ -398,7 +394,7 @@ def runtest(self):
                         self.macro, logfile=Path(self.name).with_suffix(".txt")
                     )[0]
 
-        if load_duration_supported():
+        if _is_load_duration_supported():
             load_time = result.get(LOAD_TIME_VARIABLE, None)
             if load_time is not None:
                 self.user_properties.append(("Load time", load_time))