Added action to build docs, cleaned up docstrings.

Author: LTLA

.github/workflows/build-docs.yaml

@@ -0,0 +1,40 @@
+# This workflow will install Python dependencies, run tests and lint with a single version of Python
+# For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
+
+name: Build docs
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Set up Python 3.9
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.9
+        cache: 'pip'
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install flake8 pytest tox
+
+    - name: Build docs
+      run: |
+        tox -e docs
+        touch ./docs/_build/html/.nojekyll
+
+    - name: GH Pages Deployment
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        branch: gh-pages # The branch the action should deploy to.
+        folder: ./docs/_build/html
+        clean: true # Automatically remove deleted files from the deploy branch

CHANGELOG.md

@@ -1,7 +1,5 @@
 # Changelog
 
-## Version 0.1 (development)
+## Version 0.1.0
 
-- Feature A added
-- FIX: nasty bug #1729 fixed
-- add your changes here!
+- New release of this package.

docs/conf.py

@@ -72,6 +72,7 @@
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinx_autodoc_typehints",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -171,7 +172,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = "alabaster"
+html_theme = "furo"
 
 # 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
@@ -301,4 +302,4 @@
     "pyscaffold": ("https://pyscaffold.org/en/stable", None),
 }
 
-print(f"loading configurations for {project} {version} ...", file=sys.stderr)
+print(f"loading configurations for {project} {version} ...", file=sys.stderr)

docs/index.md

@@ -1,18 +1,6 @@
 # SewerRat
 
-Add a short description here!
-
-
-## Note
-
-> This is the main page of your project's [Sphinx] documentation. It is
-> formatted in [Markdown]. Add additional pages by creating md-files in
-> `docs` or rst-files (formatted in [reStructuredText]) and adding links to
-> them in the `Contents` section below.
->
-> Please check [Sphinx] and [MyST] for more information
-> about how to document your project and how to configure your preferences.
-
+Python client for the [SewerRat](https://github.com/ArtifactDB/SewerRat) API.
 
 ## Contents
 

docs/requirements.txt

@@ -4,3 +4,5 @@
 # sphinx_rtd_theme
 myst-parser[linkify]
 sphinx>=3.2.1
+furo
+sphinx-autodoc-typehints

src/sewerrat/deregister.py

@@ -21,9 +21,6 @@ def deregister(path: str, url: str, wait: float = 1):
         wait:
             Number of seconds to wait for a file write to synchronise before
             requesting verification.
-
-    Returns:
-        On success, the directory is deregistered and nothing is returned.
     """
     path = os.path.abspath(path)
     res = requests.post(url + "/deregister/start", json = { "path": path }, allow_redirects=True)

src/sewerrat/query.py

@@ -7,7 +7,7 @@
 def query(url, text: Optional[str] = None, user: Optional[str] = None, path: Optional[str] = None, after: Optional[int] = None, before: Optional[int] = None, number: int = 100) -> List[Dict]:
     """
     Query the metadata in the SewerRat backend based on free text, the owner,
-    creation time, etc.
+    creation time, etc. This function does not require filesystem access.
 
     Args:
         url:

src/sewerrat/register.py

@@ -11,6 +11,9 @@ def register(path: str, names: List[str], url: str, wait: int = 1):
     """
     Register a directory into the SewerRat search index. It is assumed that
     that the directory is world-readable and that the caller has write access.
+    If a metadata file cannot be indexed (e.g., due to incorrect formatting,
+    insufficient permissions), a warning will be printed but the function will
+    not throw an error.
 
     Args:
         path: 
@@ -26,10 +29,6 @@ def register(path: str, names: List[str], url: str, wait: int = 1):
         wait:
             Number of seconds to wait for a file write to synchronise before
             requesting verification.
-
-    Returns:
-        On success, the directory is registered and nothing is returned.
-        A warning is raised if a metadata file cannot be indexed.
     """
     if len(names) == 0:
         raise ValueError("expected at least one entry in 'names'")