initial python docs for bdk

.github/workflows/python-api-docs.yaml

@@ -0,0 +1,34 @@
+name: Build Python API Docs Website
+
+on: workflow_dispatch
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v3
+
+      - name: "Set up Python"
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.9.x'
+
+      - name: "Install dependencies"
+        run: |
+          cd ./bdk-python/
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install sphinx sphinx-rtd-theme
+
+      - name: "Build Python API documentation"
+        run: |
+          cd ./bdk-python/
+          python scripts/generate_docs.py
+          sphinx-build -b  html -W --keep-going  docs/ docs/_build/html 
+
+#      - name: "Upload Python website"
+#        uses: actions/upload-artifact@v4
+#        with:
+#          name: artifact-python-api-docs
+#          path: /home/runner/work/bdk-ffi/bdk-ffi/bdk-python/docs/_build/html/

bdk-python/.gitignore

@@ -14,3 +14,5 @@ src/bdkpython/*.so
 build/
 
 testing-setup-py-simple-example.py
+venv
+env

bdk-python/README.md

@@ -34,3 +34,18 @@ python setup.py --verbose bdist_wheel
 ```shell
 pip install ./dist/bdkpython-<yourversion>.whl
 ```
+
+## generate the docs
+
+```shell
+python3 scripts/generate_docs.py
+sphinx-build -b  html -W --keep-going  docs/ docs/_build/html
+```
+
+To rebuild, run the following. be sure to keep the conf.py and index.rst
+
+```shell
+rm -rf docs/_build/html
+python3 scripts/generate_docs.py
+sphinx-build -b  html -W --keep-going  docs/ docs/_build/html
+```

bdk-python/docs/api.rst

@@ -0,0 +1,97 @@
+API Reference
+============
+
+.. currentmodule:: bdkpython
+
+Core Types
+----------
+
+.. autoclass:: Amount
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: FeeRate
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: Address
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Wallet Operations
+-----------------
+
+.. autoclass:: TxBuilder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: BumpFeeTxBuilder
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: Psbt
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: ElectrumClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: EsploraClient
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: Wallet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Utilities
+---------
+
+.. autoclass:: Mnemonic
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: Descriptor
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DescriptorSecretKey
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: DescriptorPublicKey
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: ChangeSet
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Exceptions
+----------
+
+.. autoclass:: InternalError
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+.. autoclass:: FeeRateError
+   :members:
+   :undoc-members:
+   :show-inheritance:
+

bdk-python/docs/conf.py

@@ -0,0 +1,31 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('..'))
+
+# Configuration file for the Sphinx documentation builder.
+project = 'BDK Python'
+copyright = '2024, Bitcoin Dev Kit'
+author = 'Bitcoin Dev Kit'
+
+# The full version, including alpha/beta/rc tags
+release = '0.1.0'
+
+# Add any Sphinx extension module names here, as strings
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.napoleon',
+    'sphinx.ext.viewcode',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The theme to use for HTML and HTML Help pages.
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets)
+html_static_path = ['_static']

bdk-python/docs/index.rst

@@ -0,0 +1,15 @@
+Welcome to BDK Python's documentation!
+========================================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

bdk-python/requirements-dev.txt

@@ -1,2 +1,4 @@
 pytest==7.1.2
 tox==3.25.1
+sphinx
+sphinx-rtd-theme

bdk-python/scripts/generate_docs.py

@@ -0,0 +1,48 @@
+import os
+import re
+
+# Define the directory where the Python source files are located
+src_dir = 'src/bdkpython'
+
+# Define the output file for the API documentation
+output_file = 'docs/api.rst'
+
+# Define categories and corresponding classes
+categories = {
+    "Core Types": ["Amount", "FeeRate", "Address"],
+    "Wallet Operations": ["TxBuilder", "BumpFeeTxBuilder", "Psbt", "Blockchain", "ElectrumClient", "EsploraClient", "Wallet"],
+    "Utilities": ["Mnemonic", "Descriptor", "DescriptorSecretKey", "DescriptorPublicKey", "ChangeSet"],
+    "Exceptions": ["InternalError", "FeeRateError"]
+}
+
+# Regex pattern to match class definitions
+class_pattern = re.compile(r'^class ([A-Za-z][A-Za-z0-9_]*)')
+
+# Scan the source directory for Python files and extract public classes
+public_classes = {}
+for root, _, files in os.walk(src_dir):
+    for file in files:
+        if file.endswith('.py'):
+            with open(os.path.join(root, file), 'r') as f:
+                for line in f:
+                    match = class_pattern.match(line)
+                    if match:
+                        class_name = match.group(1)
+                        # Only consider classes not starting with underscore
+                        if not class_name.startswith('_'):
+                            public_classes[class_name] = root
+
+# Generate the RST content
+rst_content = "API Reference\n============\n\n.. currentmodule:: bdkpython\n\n"
+
+for category, class_list in categories.items():
+    rst_content += f"{category}\n{'-' * len(category)}\n\n"
+    for class_name in class_list:
+        if class_name in public_classes:
+            rst_content += f".. autoclass:: {class_name}\n   :members:\n   :undoc-members:\n   :show-inheritance:\n\n"
+
+# Write the RST content to the output file
+with open(output_file, 'w') as f:
+    f.write(rst_content)
+
+print(f"API documentation has been generated in {output_file}")