Merge branch 'develop' into update_automatic_api_documentation

Hugovdberg · Aug 4, 2021 · 7c76b89 · 7c76b89
2 parents 48bf40a + 3050427
commit 7c76b89
Show file tree

Hide file tree

Showing 17 changed files with 59 additions and 116 deletions.
diff --git a/PIconnect/PIAF.py b/PIconnect/PIAF.py
@@ -35,10 +35,10 @@
 from warnings import warn
 
 from PIconnect._operators import OPERATORS, add_operators
-from PIconnect._utils import classproperty
 from PIconnect.AFSDK import AF
 from PIconnect.PIData import PISeriesContainer
 from PIconnect.time import timestamp_to_index
+from PIconnect._utils import classproperty
 
 _NOTHING = object()
 

diff --git a/PIconnect/time.py b/PIconnect/time.py
@@ -1,27 +1,20 @@
 from datetime import datetime
-
 import pytz
 
 from PIconnect.AFSDK import AF
 from PIconnect.config import PIConfig
 
 
 def to_af_time_range(start_time, end_time):
-    """Convert a combination of start and end time to a time range.
-
-    Both `start_time` and `end_time` can be either a :any:`datetime.datetime` object or a string.
-    `datetime` objects are first converted to a string, before being passed to
-    :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`. It is also
-    possible to specify either end as a `datetime` object, and then specify the other
-    boundary as a relative string.
+    """to_af_time_range
 
-    Args:
-        start_time (str | datetime): Start time of the time range.
-        end_time (str | datetime): End time of the time range.
+    Return AF.Time.AFTimeRange object from datetime or string
+    using :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`.
 
-    Returns:
-        :afsdk:`AF.Time.AFTimeRange <M_OSIsoft_AF_Time_AFTimeRange__ctor_1.htm>`: Time range covered by the start and end time.
+    If string is used, it is assumed that user knows the format
+    that should be passed to AF.Time.AFTimeRange.
     """
+
     if isinstance(start_time, datetime):
         start_time = start_time.isoformat()
     if isinstance(end_time, datetime):
@@ -33,11 +26,12 @@ def to_af_time_range(start_time, end_time):
 def timestamp_to_index(timestamp):
     """Convert AFTime object to datetime in local timezone.
 
-    Args:
-        timestamp (`System.DateTime`): Timestamp in .NET format to convert to `datetime`.
+    .. todo::
+
+        Allow to define timezone, default to UTC?
+
+    .. todo::
 
-    Returns:
-        `datetime`: Datetime with the timezone info from :data:`PIConfig.DEFAULT_TIMEZONE <PIconnect.config.PIConfigContainer.DEFAULT_TIMEZONE>`.
     """
     local_tz = pytz.timezone(PIConfig.DEFAULT_TIMEZONE)
     return (

diff --git a/docs/api/PIconnect.AFSDK.rst → docs/PIconnect.AFSDK.rst b/docs/api/PIconnect.AFSDK.rst → docs/PIconnect.AFSDK.rst
diff --git a/docs/PIconnect.PI.rst b/docs/PIconnect.PI.rst
@@ -0,0 +1,8 @@
+PIconnect.PI module
+===================
+
+.. automodule:: PIconnect.PI
+    :members:
+    :undoc-members:
+    :inherited-members:
+    :show-inheritance:
diff --git a/docs/api/PIconnect.time.rst → docs/PIconnect.PIAF.rst b/docs/api/PIconnect.time.rst → docs/PIconnect.PIAF.rst
@@ -1,7 +1,7 @@
-PIconnect.time module
+PIconnect.PIAF module
 =====================
 
-.. automodule:: PIconnect.time
+.. automodule:: PIconnect.PIAF
     :members:
     :undoc-members:
     :inherited-members:

diff --git a/docs/api/PIconnect.PIConsts.rst → docs/PIconnect.PIConsts.rst b/docs/api/PIconnect.PIConsts.rst → docs/PIconnect.PIConsts.rst
diff --git a/docs/api/PIconnect.PIData.rst → docs/PIconnect.PIData.rst b/docs/api/PIconnect.PIData.rst → docs/PIconnect.PIData.rst
diff --git a/docs/api/PIconnect.config.rst → docs/PIconnect.config.rst b/docs/api/PIconnect.config.rst → docs/PIconnect.config.rst
diff --git a/docs/PIconnect.rst b/docs/PIconnect.rst
@@ -0,0 +1,20 @@
+PIconnect package
+=================
+
+.. automodule:: PIconnect
+    :members:
+    :undoc-members:
+    :inherited-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+.. toctree::
+
+   PIconnect.AFSDK
+   PIconnect.config
+   PIconnect.PI
+   PIconnect.PIAF
+   PIconnect.PIConsts
+   PIconnect.PIData
diff --git a/docs/api/PI/PIconnect.PI.rst b/docs/api/PI/PIconnect.PI.rst
diff --git a/docs/api/PIAF/PIconnect.PIAF.rst b/docs/api/PIAF/PIconnect.PIAF.rst
diff --git a/docs/api/index.rst b/docs/api/index.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -20,7 +20,9 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-sys.path.insert(0, os.path.abspath(".."))
+import PIconnect
+
+# sys.path.insert(0, os.path.abspath('..'))
 
 
 class Mock(MagicMock):
@@ -33,15 +35,14 @@ def __getattr__(cls, name):
 sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
 
 # Get the project root dir, which is the parent dir of this
-# cwd = os.getcwd()
-# project_root = os.path.dirname(cwd)
+cwd = os.getcwd()
+project_root = os.path.dirname(cwd)
 
 # Insert the project root dir as the first element in the PYTHONPATH.
 # This lets us ensure that the source package is imported, and that its
 # version is used.
-# sys.path.insert(0, project_root)
+sys.path.insert(0, project_root)
 
-import PIconnect
 
 # -- General configuration ---------------------------------------------
 
@@ -54,7 +55,6 @@ def __getattr__(cls, name):
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary",
     "sphinx.ext.todo",
     "sphinx.ext.coverage",
     "sphinx.ext.githubpages",
@@ -92,8 +92,7 @@ def __getattr__(cls, name):
 extlinks = {"afsdk": ("https://docs.osisoft.com/bundle/af-sdk/page/html/%s", "")}
 
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/3.8", None),
-    "pandas": ("https://pandas.pydata.org/docs", None),
+    "pandas": ("http://pandas.pydata.org/docs", None),
     "pytz": ("http://pytz.sourceforge.net", None),
 }
 
@@ -115,7 +114,7 @@ def __getattr__(cls, name):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-autosummary_generate = True
+
 # -- Options for HTML output ----------------------------------------------
 
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -14,7 +14,7 @@ structure:
 - The basic introductions to using :py:mod:`PIconnect` are covered in the
   :doc:`/tutorials`.
 - The technical reference to all modules within :py:mod:`PIconnect` are
-  covered in :doc:`/api/index`. These also include several links to the original
+  covered in :doc:`/modules`. These also include several links to the original
   SDK documentation for important implementation details.
 - Background explanations and how-to guides still need to be written.
 
@@ -26,7 +26,7 @@ Contents
 
    installation
    tutorials
-   api/index
+   modules
    contributing
    authors
    history

diff --git a/docs/modules.rst b/docs/modules.rst
@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. toctree::
+   :maxdepth: 4
+
+   PIconnect
diff --git a/docs/tutorials.rst b/docs/tutorials.rst
@@ -21,4 +21,3 @@ Data extraction
    tutorials/interpolated_values
    tutorials/summaries
    tutorials/timezones
-   tutorials/update_value
diff --git a/docs/tutorials/update_value.rst b/docs/tutorials/update_value.rst
@@ -15,7 +15,6 @@ buffer_option as AFBufferOption.
 
 
 .. code-block:: python
-
     from datetime import datetime
     import pytz
     import PIconnect as PI