Update docs

.github/workflows/build-and-deploy-docs.yml

@@ -19,7 +19,7 @@ jobs:
             - name: Install poetry
               uses: snok/install-poetry@v1.3.3
               with:
-                version: 1.2.2
+                version: 1.8.4
                 virtualenvs-create: true
                 virtualenvs-in-project: true
                 installer-parallel: true

.github/workflows/docs-preview.yml

@@ -0,0 +1,53 @@
+name: docs/preview
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '**.py'
+
+jobs:
+  build-docs-preview:
+    name: Build docs preview
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout branch
+        uses: actions/checkout@v4
+
+      - name: Setup python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.10.5
+
+      - name: Install poetry
+        uses: snok/install-poetry@v1.3.3
+        with:
+          version: 1.8.4
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ hashFiles('**/poetry.lock') }}
+
+      - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction --no-root
+
+      - name: Build docs
+        run: |
+          source .venv/bin/activate
+          cd docs
+          make clean
+          make html
+          cd ..
+
+      - name: Upload docs artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-preview-${{ github.event.pull_request.number }}
+          path: docs/_build/html
+          retention-days: 7

.github/workflows/release.yml

@@ -19,7 +19,7 @@ jobs:
             - name: Install poetry
               uses: snok/install-poetry@v1.3.3
               with:
-                version: 1.2.2
+                version: 1.8.4
                 virtualenvs-create: true
                 virtualenvs-in-project: true
                 installer-parallel: true

.github/workflows/test-and-verify.yml

@@ -19,7 +19,7 @@ jobs:
       - name: Install poetry
         uses: snok/install-poetry@v1
         with:
-          version: 1.2.2
+          version: 1.8.4
           virtualenvs-create: true
           virtualenvs-in-project: true
           installer-parallel: true

.gitignore

@@ -117,6 +117,9 @@ venv.bak/
 .spyderproject
 .spyproject
 
+# VScode workspace settings
+.vscode
+
 # Rope project settings
 .ropeproject
 

docs/api.rst

@@ -1,6 +1,60 @@
 API Reference
 =============
 
-.. click:: quantaq_cli.console:main
+CLI
+---
+
+.. click:: quantaq_cli.cli:main
    :prog: quantaq-cli
-   :show-nested:
+   :nested: full
+
+quantaq_cli.toolkit
+----------------------
+
+concat
+~~~~~~
+
+.. automodule:: quantaq_cli.toolkit.concat
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+expunge
+~~~~~~~
+
+.. automodule:: quantaq_cli.toolkit.expunge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+flag
+~~~~
+
+.. automodule:: quantaq_cli.toolkit.flag
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+merge
+~~~~~
+
+.. automodule:: quantaq_cli.toolkit.merge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+munge
+~~~~~
+
+.. automodule:: quantaq_cli.toolkit.munge
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+resample
+~~~~~~~~
+
+.. automodule:: quantaq_cli.toolkit.resample
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/conf.py

@@ -35,16 +35,18 @@
 
 
 # -- General configuration ---------------------------------------------------
+autosummary_generate = True
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon', # google-style docstrings
     'sphinx_click.ext',
     'sphinx.ext.intersphinx',
-    'recommonmark',
+    'myst_parser',
     "sphinx_rtd_theme"
 ]
 
@@ -56,6 +58,11 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = True
+napoleon_use_param = True
+napoleon_use_rtype = True
 
 # -- Options for HTML output -------------------------------------------------
 

docs/contributing.rst

@@ -38,8 +38,8 @@ Testing
 
     $ poetry run pytest -rP
 
-We support a number of Python versions. Currently, we support and test for 3.8, 
-3.9, and 3.10. These tests are automated and run as GitHub actions on every 
+We support a number of Python versions. Currently, we support and test for 3.9, 
+3.10, and 3.11. These tests are automated and run as GitHub actions on every 
 pull request.
 
 .. _issue tracker: https://github.com/quant-aq/cli/issues

docs/index.rst

@@ -6,8 +6,8 @@
 quantaq-cli
 ============
 
-**QuantAQ-CLI** provides an easy-to-use command line interface for munging and 
-interacting with QuantAQ air quality sensor data.
+**QuantAQ-CLI** provides an easy-to-use Python library and command line 
+interface for munging and interacting with QuantAQ air quality sensor data.
 
 
 .. toctree::
@@ -17,5 +17,3 @@ interacting with QuantAQ air quality sensor data.
    usage
    contributing
    api
-
-