Merge pull request #16 from decarlof/master

Improved and cleaned up docs
xray-imaging · Mar 29, 2024 · 68ce442 · 68ce442
2 parents b3f0463 + dfe4073
commit 68ce442
Show file tree

Hide file tree

Showing 21 changed files with 69 additions and 3 deletions.
diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -3,7 +3,7 @@
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
 version: 2
 sphinx:
-  configuration: doc/conf.py
+  configuration: docs/conf.py
 # Set the version of Python and other tools you might need
 python:
   install:

diff --git a/dmagic/__init__.py b/dmagic/__init__.py
@@ -48,4 +48,4 @@
 
 from dmagic.scheduling import *
 from dmagic.pv import *
-from dmagic.util import *
+from dmagic.utils import *
diff --git a/dmagic/pv.py b/dmagic/pv.py
@@ -60,9 +60,23 @@
 __author__ = "Francesco De Carlo"
 __copyright__ = "Copyright (c) 2015-2016, UChicago Argonne, LLC."
 __docformat__ = 'restructuredtext en'
+__all__ = ['init_PVs',
+           'update']
 
 
 def init_PVs(args):
+    """
+    Initialize the EPICS PVs that will hold user and experiment information
+
+    Parameters
+    ----------
+    args.tomoscan_prefix : EPICS IOC prefix, e.g. 2bma:TomoScan:
+
+    Returns
+    -------
+    user_pvs : dict
+        A dictionary of EPICS PVs
+    """
 
     user_pvs = {}
     tomoscan_prefix = args.tomoscan_prefix
@@ -79,6 +93,13 @@ def init_PVs(args):
 
 
 def update(args, date=None):
+    """
+    Update the EPICS PVs with user and experiment information associated with the current experiment
+
+    Parameters
+    ----------
+    args : parametars passed at the CLI 
+    """
 
     auth      = scheduling.authorize()
     run       = scheduling.current_run(auth, args)

diff --git a/dmagic/utils.py b/dmagic/utils.py
@@ -50,9 +50,22 @@
 Module containing utils routines to access the APS scheduling system.
 """
 
+__all__ = ['fix_iso']
+
 def fix_iso(s):
     """
     This is a temporary fix until timezone is returned as -05:00 instead of -0500
+
+    Parameters
+    ----------
+    s : string
+        Like "2022-07-31T01:51:05-0400"
+
+    Returns
+    -------
+    s : string
+        Like "2022-07-31T01:51:05-04:00"
+
     """
     pos = len("2022-07-31T01:51:05-0400") - 2 # take off end "00"
     if len(s) == pos:                 # missing minutes completely

diff --git a/doc/Makefile → docs/Makefile b/doc/Makefile → docs/Makefile
diff --git a/doc/conf.py → docs/conf.py b/doc/conf.py → docs/conf.py
@@ -139,6 +139,9 @@
     'logo_only': True,
 }
 
+html_logo = 'source/img/dmagic-logo.png'
+html_favicon = 'source/img/dmagic-logo.png'
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

diff --git a/doc/demo/epics/DTaggingUpdate.adl → docs/demo/epics/DTaggingUpdate.adl b/doc/demo/epics/DTaggingUpdate.adl → docs/demo/epics/DTaggingUpdate.adl
diff --git a/doc/demo/epics/experimentInfo.db → docs/demo/epics/experimentInfo.db b/doc/demo/epics/experimentInfo.db → docs/demo/epics/experimentInfo.db
diff --git a/doc/demo/epics/experimentInfo_settings.req → docs/demo/epics/experimentInfo_settings.req b/doc/demo/epics/experimentInfo_settings.req → docs/demo/epics/experimentInfo_settings.req
diff --git a/doc/demo/epics/experiment_info.adl → docs/demo/epics/experiment_info.adl b/doc/demo/epics/experiment_info.adl → docs/demo/epics/experiment_info.adl
diff --git a/doc/index.rst → docs/index.rst b/doc/index.rst → docs/index.rst
diff --git a/doc/make.bat → docs/make.bat b/doc/make.bat → docs/make.bat
diff --git a/doc/source/about.rst → docs/source/about.rst b/doc/source/about.rst → docs/source/about.rst
diff --git a/doc/source/api.rst → docs/source/api.rst b/doc/source/api.rst → docs/source/api.rst
@@ -8,7 +8,9 @@ for `DMagic <https://github.com/decarlof/DMagic>`_.
 
 .. toctree::
 
-   dmagic.scheduling
+   api/dmagic.pv
+   api/dmagic.scheduling
+   api/dmagic.utils
 
 
 .. automodule:: dmagic

diff --git a/docs/source/api/dmagic.pv.rst b/docs/source/api/dmagic.pv.rst
@@ -0,0 +1,14 @@
+:mod:`dmagic.pv`
+================
+
+.. automodule:: dmagic.pv
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+   .. rubric:: **Functions:**
+
+   .. autosummary::
+
+      init_PVs
+      update
diff --git a/doc/source/api/dmagic.scheduling.rst → docs/source/api/dmagic.scheduling.rst b/doc/source/api/dmagic.scheduling.rst → docs/source/api/dmagic.scheduling.rst
diff --git a/docs/source/api/dmagic.utils.rst b/docs/source/api/dmagic.utils.rst
@@ -0,0 +1,13 @@
+:mod:`dmagic.utils`
+===================
+
+.. automodule:: dmagic.utils
+   :members:
+   :show-inheritance:
+   :undoc-members:
+
+   .. rubric:: **Functions:**
+
+   .. autosummary::
+
+      fix_iso
diff --git a/doc/source/img/dmagic-logo.png → docs/source/img/dmagic-logo.png b/doc/source/img/dmagic-logo.png → docs/source/img/dmagic-logo.png
diff --git a/doc/source/img/medm_screen.png → docs/source/img/medm_screen.png b/doc/source/img/medm_screen.png → docs/source/img/medm_screen.png
diff --git a/doc/source/install.rst → docs/source/install.rst b/doc/source/install.rst → docs/source/install.rst
diff --git a/doc/source/usage.rst → docs/source/usage.rst b/doc/source/usage.rst → docs/source/usage.rst