docs

Author: rog555

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.11'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install -e .
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: make docs
+
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v2

.github/workflows/release.yml

@@ -1,4 +1,4 @@
-name: Release to PyPI
+name: release
 
 on:
   push:

Makefile

@@ -16,3 +16,6 @@ style:
 	pre-commit run --all-files
 
 check: style test
+
+docs:
+	pdoc ./abnosql '!abnosql.cli'

abnosql/__init__.py

@@ -2,14 +2,16 @@
 
 from abnosql.cli import cli
 from abnosql.table import table
-
-__version__ = '0.0.1'
+from abnosql.table import TableBase
+from abnosql.table import TableSpecs
 
 
 logger = logging.getLogger(__name__)
 logger.addHandler(logging.NullHandler())
 
 __all__ = [  # type: ignore
     cli,
-    table
+    table,
+    TableBase,
+    TableSpecs
 ]

abnosql/table.py

@@ -20,9 +20,11 @@ def set_config(self, table: str) -> t.Dict:  # type: ignore[empty-body] # noqa E
         """Hook to set config
 
         Args:
+
             table: table name
 
         Returns:
+
             dictionary containing config
 
         """
@@ -33,10 +35,12 @@ def get_item_post(self, table: str, item: t.Dict) -> t.Dict:  # type: ignore[emp
         """Hook invoked after get_item()
 
         Args:
+
             table: table name
             item: dictionary item retrieved from get_item call
 
         Returns:
+
             dictionary containing updated item
 
         """
@@ -47,6 +51,7 @@ def put_item_post(self, table: str, item: t.Dict) -> None:  # type: ignore[empty
         """Hook invoked after put_item()
 
         Args:
+
             table: table name
             item: dictionary containing partition and range/sort key
 
@@ -58,6 +63,7 @@ def put_items_post(self, table: str, items: t.List[t.Dict]) -> None:  # type: ig
         """Hook invoked after put_items()
 
         Args:
+
             table: table name
             item: list of dictionary items written to table
 
@@ -69,6 +75,7 @@ def delete_item_post(self, table: str, key: t.Dict) -> None:  # type: ignore[emp
         """Hook invoked after delete_item()
 
         Args:
+
             table: table name
             key: dictionary of item written to table
 
@@ -84,6 +91,7 @@ def __init__(
         """Instantiate table object
 
         Args:
+
             pm: pluggy plugin manager
             name: table name
             config: optional config dict dict
@@ -95,9 +103,11 @@ def get_item(self, **kwargs) -> t.Dict:
         """Get table/collection item
 
         Args:
+
             partition key and range/sort key (if used)
 
         Returns:
+
             item dictionary or None if not found
 
         """
@@ -108,6 +118,7 @@ def put_item(self, item: t.Dict):
         """Puts table/collection item
 
         Args:
+
             item: dictionary
 
         """
@@ -118,6 +129,7 @@ def put_items(self, items: t.Iterable[t.Dict]):
         """Puts multiple table/collection items
 
         Args:
+
             items: list of item dictionaries
 
         """
@@ -144,6 +156,7 @@ def query(
         """Perform key based query with optional exact match filters
 
         Args:
+
             key: dictionary containing partition key and range/sort key
             filters: optional dictionary of key=value to query and filter on
             limit: query limit
@@ -166,6 +179,7 @@ def query_sql(
         """Perform key based query with optional exact match filters
 
         Args:
+
             statement: SQL statement to query table
             parameters: optional dictionary containing @key = value placeholders
             limit: query limit

docs/abnosql.html

@@ -0,0 +1,7 @@
+<!doctype html>
+<html>
+<head>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./abnosql/table.html"/>
+</head>
+</html>

docs/abnosql/table.html

@@ -46,6 +46,7 @@ def get_version():
     'responses'
 ]
 dev_require = tests_require + [
+    'pdoc',
     'pre-commit'
 ]