Build and Upload HTML API Documentation

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

@@ -0,0 +1,184 @@
+name: Build and Upload Python API Docs
+
+on:
+  workflow_dispatch:
+
+permissions: {}
+
+jobs:
+  build-manylinux_2_28-x86_64-api-docs:
+    name: "Build and upload docs on Manylinux 2.28 x86_64"
+    runs-on: ubuntu-24.04
+    container:
+      image: quay.io/pypa/manylinux_2_28_x86_64
+      env:
+        PLAT: manylinux_2_28_x86_64
+        PYBIN: "/opt/python/${{ matrix.python }}/bin"
+    strategy:
+      matrix:
+        python:
+          - cp310-cp310
+          - cp311-cp311
+          - cp312-cp312
+          - cp313-cp313
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: "Configure Git safe directory"
+        run: git config --global --add safe.directory /__w/bdk-python/bdk-python
+
+      - name: "Install Rust 1.84.1"
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: 1.84.1
+
+      - name: "Generate bdk.py"
+        run: bash ./scripts/generate-linux.sh
+
+      - name: "Install Sphinx and Theme"
+        run: ${PYBIN}/pip install sphinx sphinx_rtd_theme
+
+      - name: "Generate python API Documentation"
+        run: |
+          ${PYBIN}/python ./docs/generate_docs.py
+
+      - name: "Build HTML Documentation"
+        run: |
+          ${PYBIN}/python -m sphinx -b html -W --keep-going  docs/source docs/_build/html
+
+      - name: "Upload API Docs"
+        uses: actions/upload-artifact@v4
+        with:
+          name: bdkpython-manylinux_2_28_x86_64-${{ matrix.python }}-api-docs
+          path: /home/runner/work/bdk-python/bdk-python/docs/_build/html
+
+  build-macos-arm64-api-docs:
+    name: "Build and upload docs on macOS arm64"
+    runs-on: macos-14
+    strategy:
+      matrix:
+        python:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: "Install Python"
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: "Generate bdk.py"
+        run: bash ./scripts/generate-macos-arm64.sh
+
+      - name: "Install Sphinx and Theme"
+        run: pip3 install sphinx sphinx_rtd_theme
+
+      - name: "Generate python API Documentation"
+        run: |
+          python3 ./docs/generate_docs.py
+
+      - name: "Build HTML Documentation"
+        run: |
+          python3 -c "import platform; print(platform.machine())"
+          python3 -m sphinx -b html -W --keep-going -v docs/source docs/_build/html
+
+      - name: "Upload API Docs"
+        uses: actions/upload-artifact@v4
+        with:
+          name: bdkpython-macos-arm64-${{ matrix.python }}-api-docs
+          path: /Users/runner/work/bdk-python/bdk-python/docs/_build/html
+
+  build-macos-x86_64-api-docs:
+    name: "Build and upload docs on macOS x86_64"
+    runs-on: macos-13
+    strategy:
+      matrix:
+        python:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          persist-credentials: false
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: "Generate bdk.py"
+        run: bash ./scripts/generate-macos-x86_64.sh
+
+      - name: "Install Sphinx and Theme"
+        run: pip3 install sphinx sphinx_rtd_theme
+
+      - name: "Generate python API Documentation"
+        run: |
+          python3 ./docs/generate_docs.py
+      - name: "Build HTML Documentation"
+        run: python3 -m sphinx -b html -W --keep-going  docs/source docs/_build/html
+
+      - name: "Upload API Docs"
+        uses: actions/upload-artifact@v4
+        with:
+          name: bdkpython-macos-x86_64-${{ matrix.python }}
+          path: /Users/runner/work/bdk-python/bdk-python/docs/_build/html
+
+  build-windows-api-docs:
+    name: "Build and upload docs on Windows"
+    runs-on: windows-2022
+    strategy:
+      matrix:
+        python:
+          - "3.10"
+          - "3.11"
+          - "3.12"
+          - "3.13"
+    steps:
+      - name: "Checkout"
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          persist-credentials: false
+          fetch-depth: 0
+
+      - name: "Install Python"
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python }}
+
+      - name: "Generate bdk.py"
+        run: bash ./scripts/generate-windows.sh
+
+      - name: "Install Sphinx and Theme"
+        run: pip install sphinx sphinx_rtd_theme
+
+      - name: "Generate python API Documentation"
+        run: |
+          python ./docs/generate_docs.py
+
+      - name: "Build HTML Documentation"
+        run: python -m sphinx -b html -W --keep-going  docs/source docs/_build/html
+
+      - name: "Upload API Docs"
+        uses: actions/upload-artifact@v4
+        with:
+          name: bdkpython-windows-${{ matrix.python }}
+          path: D:\a\bdk-python\bdk-python\docs/_build/html

.gitignore

@@ -63,3 +63,7 @@ build/
 
 testing-setup-py-simple-example.py
 .localpythonenv/
+
+# API docs
+api.rst
+_build/

README.md

@@ -30,3 +30,14 @@ pip3 install ./dist/bdkpython-<yourversion>.whl --force-reinstall
 
 python3 -m unittest --verbose
 ```
+
+## Build HTML API Documentation (Optional)
+
+6. Generate docs
+7. Build HTML Documentation
+
+```sh
+python3 ./docs/generate_docs.py
+
+python3 -m sphinx -b html -W --keep-going -v docs/source docs/_build/html
+```

docs/generate_docs.py

@@ -0,0 +1,51 @@
+import os
+import re
+import subprocess
+import shutil
+
+# ----------------
+# Generate API RST
+# ----------------
+
+# Define the directory where the Python source files are located
+src_dir = 'src/bdkpython'
+package_root = 'bdkpython'
+
+# Define the output file for the API documentation
+output_file = 'docs/source/api.rst'
+
+# Regex pattern to match class definitions
+class_pattern = re.compile(r'^class ([A-Za-z][A-Za-z0-9_]*)')
+
+# Store classes with their full module path
+public_classes = {}
+
+for root, _, files in os.walk(src_dir):
+    for file in files:
+        if file.endswith('.py'):
+            module_path = os.path.relpath(os.path.join(root, file), src_dir)
+            module_path = module_path.replace(os.sep, '.').removesuffix('.py')
+            full_module = f'{package_root}.{module_path}'
+            with open(os.path.join(root, file), 'r', encoding='utf-8') as f:
+                for line in f:
+                    match = class_pattern.match(line)
+                    if match:
+                        class_name = match.group(1)
+                        if not class_name.startswith('_'):
+                            fqcn = f'{full_module}.{class_name}'
+                            public_classes[fqcn] = True
+
+# Generate the RST content
+rst_content = "API Reference\n============\n\n"
+
+for fqcn in sorted(public_classes.keys()):
+    rst_content += f".. autoclass:: {fqcn}\n"
+    rst_content += "   :members:\n"
+    rst_content += "   :undoc-members:\n"
+    rst_content += "   :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}")

docs/source/_static/css/custom.css

@@ -0,0 +1,8 @@
+/* Remove max-width restriction */
+.wy-nav-content {
+    max-width: none !important;
+}
+
+.wy-menu-vertical a {
+    font-size: 1.1em !important;
+}

docs/source/conf.py

@@ -0,0 +1,50 @@
+# 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
+
+import os
+import sys
+sys.path.insert(0, os.path.abspath('../../src'))
+
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'bdkpython'
+copyright = '2025, Bitcoin Dev Kit Developers'
+author = 'Bitcoin Dev Kit Developers'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.viewcode',
+    'sphinx_rtd_theme',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# Suppress docstring formatting warnings due to uniffi bindings
+suppress_warnings = [
+    'docutils'
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# Register custom CSS
+html_css_files = [
+    'css/custom.css',
+]
+
+def setup(app):
+    app.add_css_file('css/custom.css')

docs/source/index.rst

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

requirements-dev.txt

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