Update Docs and Reorganize (#4)

* update sphinx build directory

* update datasource.py docs

* update datasource.py docs for remaining classes

* update datasource.py to add type hints for return values that were missing

* change copyright in docs

* reorganize, add linting test

* documentation fix after reorg

* fix linting errors

* update readme

Author: tipatterson-dev

.github/workflows/docs_pages.yaml

@@ -22,11 +22,11 @@ jobs:
 
     - name: Sphinx build
       run: |
-        poetry run sphinx-build -M html docs/source docs/build/
+        poetry run sphinx-build -b html docs/source docs/build/html
 
     - name: Deploy documentation
-      uses: peaceiris/actions-gh-pages@v3
-      if: github.event_name == 'push' && github.ref == 'refs/heads/master'
+      uses: peaceiris/actions-gh-pages@v4
+      if: github.event_name == 'push' && github.ref == 'refs/heads/docs'
       with:
         publish_branch: gh-pages
         github_token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/linting.yaml

@@ -0,0 +1,20 @@
+name: Flake8 Linting
+on: [ push, pull_request ]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Poetry
+        uses: snok/install-poetry@v1
+
+      - name: Install dependencies
+        run: |
+          poetry install --with dev
+      - name: Lint
+        run: |
+          poetry run flake8

README.md

@@ -3,6 +3,8 @@
 Library for communicating with Opensensorhub that provides options for saving configurations, getting visualization 
 recommendations for data, retrieving data in real time, archival streams, and batch modes, and more.
 
+API Documentation available [here](hhttps://botts-innovative-research.github.io/OSHConnect-Python/)
+
 Links:  
  * [Architecture Doc](https://docs.google.com/document/d/1pIaeQw0ocU6ApNgqTVRZuSwjJAbhCcmweMq6RiVYEic/edit?usp=sharing)
  * [UML Diagram](https://drive.google.com/file/d/1FVrnYiuAR8ykqfOUa1NuoMyZ1abXzMPw/view?usp=drive_link)

docs/source/api.rst

@@ -0,0 +1,69 @@
+API Reference
+=============
+
+OSHConnect
+----------
+
+
+OSHConnect Utilities and Helpers
+--------------------------------
+.. automodule:: oshconnect.oshconnectapi
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+OSH Connect Data Models
+-----------------------
+These are the second highest level pieces in the hierarchy of the library and the utilities needed to help almost
+everything else in the app function.
+
+.. automodule:: oshconnect.osh_connect_datamodels
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+DataSources and Messaging
+-------------------------
+Due to their extreme importance in the library, the data sources are listed separately along with the classes that help
+manage them and their data.
+
+.. automodule:: oshconnect.datasource
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Time Management
+---------------
+Currently **WIP** but this module will contain the classes and functions that help manage the current time and other
+playback features of groups of datasources/datafeeds
+
+.. automodule:: oshconnect.timemanagement
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Styling
+-------
+**WIP** This module contains the classes and functions that help manage the styling and visualization recommendations that
+the library provides.
+
+Datastore
+---------
+**WIP** This module is for managing the state of the app. The configurations files are intended to be interchgangale
+among all language versions of the OSHConnect ecosystem.
+
+Core Data Models
+----------------
+Theses data models are not often intended to be used directly by the user, but are used by the library to help manage
+validation of data that flows to and from the API.
+
+.. automodule:: oshconnect.core_datamodels
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+
+
+Helpers
+~~~~~~~

docs/source/conf.py

@@ -6,8 +6,23 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
+import os
+import sys
+import traceback
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+
+def process_exception(app, what, name, obj, options, lines):
+    traceback.print_exc()
+
+
+def setup(app):
+    app.connect('autodoc-process-docstring', process_exception)
+
+
 project = 'OSHConnect-Python'
-copyright = '2024, Ian Patterson'
+copyright = '2024, Botts Innovative Research, Inc.'
 author = 'Ian Patterson'
 release = '0.1'
 
@@ -27,5 +42,10 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
 html_static_path = ['_static']
+html_theme_options = {
+    'sticky_navigation': True,
+    'display_version': True,
+    'prev_next_buttons_location': 'both',
+}

docs/source/datasources.rst

@@ -0,0 +1,2 @@
+DataSources
+==============

docs/source/external.rst

@@ -0,0 +1,2 @@
+External Models
+===============

docs/source/index.rst

@@ -1,14 +1,21 @@
-.. OSHConnect-Python documentation master file, created by
-   sphinx-quickstart on Tue Jun 25 11:43:33 2024.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Welcome to OSHConnect-Python's documentation!
 =============================================
 
+OSHConnect-Python
+=================
+OSHConnect-Python is the Python version of the OSHConnect family of application libraries inteded to provide a simple
+and straightforward way to interact with OpenSensorHub (or another CSAPI server) by way of OGC API - Connected Systems.
+It supports or will support at the time of a 1.0 release Part 1 and Part 2 of the Connected Systems api, as well as
+certain streaming features made possible by OpenSensorHub.
+
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
+   :caption: Contents
+
+   api
+   datasources
+   external
+
 
 
 
@@ -20,17 +27,3 @@ Indices and tables
 * :ref:`search`
 
 
-OSHConnect-Python
-=================
-OSHConnect-Python is the Python version of the OSHConnect family of application libraries inteded to provide a simple
-and straightforward way to interact with OpenSensorHub (or another CSAPI server) by way of OGC API - Connected Systems.
-It supports or will support at the time of a 1.0 release Part 1 and Part 2 of the Connected Systems api, as well as
-certain streaming features made possible by OpenSensorHub.
-
-OSHConnect
-==========
-
-.. automodule:: oshconnect
-    :members:
-    :undoc-members:
-    :show-inheritance:

external_models/__init__.py

@@ -5,28 +5,5 @@
 #   Contact Email:  ian@botts-inc.com
 #   ==============================================================================
 
-import base64
-from dataclasses import dataclass
-from enum import Enum
-
-
-@dataclass(kw_only=True)
-class Endpoints:
-    root: str = "sensorhub"
-    sos: str = f"{root}/sos"
-    connected_systems: str = f"{root}/api"
-
-
-class TemporalModes(Enum):
-    REAL_TIME = "realtime"
-    ARCHIVE = "archive"
-    BATCH = "batch"
-    RT_SYNC = "realtimesync"
-    ARCHIVE_SYNC = "archivesync"
-
-
-class Utilities:
-
-    @staticmethod
-    def convert_auth_to_base64(username: str, password: str) -> str:
-        return base64.b64encode(f"{username}:{password}".encode()).decode()
+class Example:
+    pass