Merge pull request #2 from algorandfoundation/docs

docs: sphinx, autodoc2, doctests setup

.github/workflows/check-python.yaml

@@ -28,10 +28,10 @@ jobs:
           set -o pipefail
           poetry run pre-commit run --all-files && git diff --exit-code
 
-      # - name: Check documentation
-      #   run: |
-      #     set -o pipefail
-      #     poetry run poe docs
+      - name: Check documentation
+        run: |
+          set -o pipefail
+          poetry run poe docs-test
 
       - name: Check wheels can be built
         run: |

.github/workflows/gh-pages.yaml

@@ -0,0 +1,42 @@
+name: "Sphinx: Render + publish docs"
+
+on:
+  workflow_call:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    steps:
+      - name: Checkout source code
+        uses: actions/checkout@v4
+
+      - name: Install poetry
+        run: pipx install poetry
+
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: "poetry"
+
+      - name: Install dependencies
+        run: poetry install --no-interaction
+
+      - name: Test doctests
+        run: poetry run poe docs-test
+
+      - name: Build docs
+        run: poetry run poe docs-build
+
+      - name: Upload to GitHub pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/_build
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,4 +1,12 @@
+.idea
 __pycache__
-# coverage output
+.DS_Store
+
+/docs/_build/
+/docs/apidocs/
+
 .coverage
-coverage.xml
+coverage.xml
+.venv*
+
+/dist

README.md

@@ -1 +1,16 @@
-# Algorand Subscriber
+<div align="center">
+<a href="/~https://github.com/algorandfoundation/algokit-subscriber-py"><img src="https://bafybeidbb3a7cgn3unoz4oouk2jme4eavqgqtnskfr4bqhbjku3s52de4a.ipfs.w3s.link/algokit-subscriber-logo.png" width=60%></a>
+</div>
+
+<p align="center">
+    <a target="_blank" href="https://algorandfoundation.github.io/algokit-subscriber-py/"><img src="https://img.shields.io/badge/docs-repository-74dfdc?logo=github&style=flat.svg" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img src="https://img.shields.io/badge/learn-AlgoKit-74dfdc?logo=algorand&mac=flat.svg" /></a>
+    <a target="_blank" href="/~https://github.com/algorandfoundation/algokit-subscriber-py"><img src="https://img.shields.io/github/stars/algorandfoundation/algokit-subscriber-py?color=74dfdc&logo=star&style=flat" /></a>
+    <a target="_blank" href="https://developer.algorand.org/algokit/"><img  src="https://api.visitorbadge.io/api/visitors?path=https%3A%2F%2Fgithub.com%2Falgorandfoundation%2Falgokit-subscriber-py&countColor=%2374dfdc&style=flat" /></a>
+</p>
+
+---
+
+Algorand Subscriber is a Python library for subscribing and managing events on the Algorand blockchain.
+
+## To be expanded

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/custom.css

@@ -0,0 +1,14 @@
+/*
+ Hide the first element of attribute like items as algopy stubs are more like interfaces and as such
+ should not indicate a specific "value" for variables
+ */
+.py.data,
+.py.attribute {
+    dd p:first-child {
+        display: none;
+    }
+}
+
+.py.class {
+    margin-top: 3rem;
+}

docs/api.md

@@ -0,0 +1,18 @@
+# API Reference
+
+```{py:module} algokit_subscriber_py
+:no-index:
+```
+
+```{autodoc2-docstring} algokit_subscriber_py
+:allowtitles:
+```
+
+## Contents
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+apidocs/algokit_subscriber_py/algokit_subscriber_py
+```

docs/conf.py

@@ -0,0 +1,89 @@
+# ruff: noqa
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "Algorand Python Testing"
+copyright = "2024, Algorand Foundation"  # noqa: A001
+author = "Algorand Foundation"
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.githubpages",
+    "sphinx.ext.intersphinx",
+    "sphinx_copybutton",
+    "myst_parser",
+    "autodoc2",
+    "sphinx.ext.doctest",
+    "sphinxmermaid",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+nitpick_ignore = [("py:class", "optional")]
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# warning exclusions
+suppress_warnings = [
+    "myst.xref_missing",
+    "autodoc2.dup_item",
+    "ref.python",  # Ignore Python reference warnings
+    "ref.class",  # Ignore class reference warnings
+    "ref.obj",  # Ignore object reference warnings
+    "toc.excluded",  # Ignore warnings about documents not in any toctree
+]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+html_theme = "furo"
+html_static_path = ["_static"]
+html_css_files = [
+    "custom.css",
+]
+
+python_maximum_signature_line_length = 80
+
+# -- Options for myst ---
+myst_enable_extensions = ["colon_fence", "fieldlist"]
+
+# -- Options for autodoc2
+autodoc2_packages = [
+    {
+        "path": "../src/algokit_subscriber_py",
+        "auto_mode": True,
+    },
+]
+autodoc2_render_plugin = "myst"
+autodoc2_hidden_objects = [
+    "private",
+]
+add_module_names = False
+autodoc2_index_template = None
+
+# -- Options for doctest --
+doctest_test_doctest_blocks = "default"
+
+# -- Options for mermaid --
+sphinxmermaid_mermaid_init = {
+    "theme": "dark",
+}
+
+# Ignore specific warning types
+# TODO : remove upon refining autodoc2 (or finding alternative to sphinx)
+suppress_warnings = [
+    "myst.xref_missing",
+    "autodoc2.dup_item",
+    "ref.python",  # Ignore Python reference warnings
+    "ref.class",  # Ignore class reference warnings
+    "ref.obj",  # Ignore object reference warnings
+]

docs/README.md → docs/index.md

@@ -2,37 +2,53 @@
 
 ## Quick start
 
-```python
-// Create subscriber
-const subscriber = AlgorandSubscriber(
-  {
-    "filters": [
-      {
-        "name": "filter1",
-        "filter": {
-          "type": "pay",
-          "sender": "ABC...",
+```{testcode}
+# Import necessary modules
+from algokit_subscriber_py import AlgorandSubscriber
+from algosdk.v2client import algod
+from algokit_utils import get_algod_client, get_algonode_config
+
+# Create an Algod client
+algod_client = get_algod_client(get_algonode_config("testnet", "algod", "")) # testnet used for demo purposes
+
+# Create subscriber (example with filters)
+subscriber = AlgorandSubscriber(
+    config={
+        "filters": [
+            {
+                "name": "filter1",
+                "filter": {
+                    "type": "pay",
+                    "sender": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ",
+                },
+            },
+        ],
+        "watermark_persistence": {
+            "get": lambda: 0,
+            "set": lambda x: None
         },
-      },
-    ],
-    # ... other options (use intellisense to explore)
-  },
-  algod,
-  optionalIndexer
-);
+        "sync_behaviour": "skip-sync-newest",
+        "max_rounds_to_sync": 100,
+    },
+    algod_client=algod_client,
+)
 
 # Set up subscription(s)
-subscriber.on("filter1", lambda: transaction ... )
-#...
+subscriber.on("filter1", lambda transaction, _: print(f"Received transaction: {transaction['id']}"))
 
 # Set up error handling
-subscriber.on_error(lambda: error ... )
+subscriber.on_error(lambda error, _: print(f"Error occurred: {error}"))
 
 # Either: Start the subscriber (if in long-running process)
-subscriber.start();
+# subscriber.start()
 
 # OR: Poll the subscriber (if in cron job / periodic lambda)
-subscriber.poll_once();
+result = subscriber.poll_once()
+print(f"Polled {len(result['subscribed_transactions'])} transactions")
+```
+
+```{testoutput}
+Polled 0 transactions
 ```
 
 ## Capabilities
@@ -425,3 +441,19 @@ frame_dig 0 // or any other command to put the ARC-4 encoded bytes for the event
 concat
 log
 ```
+
+## Next steps
+
+To dig deeper into the capabilities of `algorand-python-testing`, continue with the following sections.
+
+```{toctree}
+---
+maxdepth: 2
+caption: Contents
+hidden: true
+---
+
+subscriber
+subscriptions
+api
+```

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/subscriptions.md

@@ -131,7 +131,7 @@ Each filter you provide within this type will apply an AND logic between the spe
 
 ```typescript
 "filter": {
-  "type": "axfer,
+  "type": "axfer",
   "sender": "ABC..."
 }
 ```