[Python] Configure Sphinx docs

.github/workflows/python_push.yml

@@ -35,7 +35,7 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
         with:
-          python-version: ${{ matrix.python-version }}
+          python-version: ${{ matrix.pyVersion }}
           version: "0.6.5"
 
       - name: Run tests
@@ -54,8 +54,24 @@ jobs:
         uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
         with:
           version: "0.6.5"
-          checksum: "8fc9895719a1291ecd193cb86f9282ff3649cef797d29eacc74c4f573aab1e2f"
 
       - name: Run lint
         working-directory: experimental/python
         run: make lint
+
+  python_docs:
+    name: docs
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository and submodules
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
+        with:
+          version: "0.6.5"
+
+      - name: Run docs
+        working-directory: experimental/python
+        run: make docs

experimental/python/.gitignore

@@ -6,7 +6,7 @@ __pycache__/
 *$py.class
 
 # Sphinx
-_output
+docs/_output
 docs/_build/
 
 # Distribution / packaging

experimental/python/Makefile

@@ -4,6 +4,10 @@ fmt:
 	uv run ruff check --fix $(sources) || true
 	uv run ruff format
 
+docs:
+	# Python 3.12+ is needed for get_overloads
+	uv run --python 3.12 sphinx-build docs docs/_output --fail-on-warning --show-traceback --nitpicky --fresh-env --keep-going
+
 lint:
 	# check if lock matches the project metadata
 	uv lock --check 
@@ -18,3 +22,5 @@ test:
 build:
 	rm -rf build dist
 	uv build .
+
+.PHONY: fmt docs lint test build

experimental/python/docs/conf.py

@@ -0,0 +1,76 @@
+# 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
+
+import sys
+import os
+
+sys.path.append(os.path.abspath(".."))
+sys.path.append(os.path.abspath("ext"))
+
+
+project = "databricks-bundles"
+copyright = "2024, Databricks"
+author = "Gleb Kanterov"
+release = "beta"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "autodoc_databricks_bundles",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
+]
+
+autodoc_typehints = "signature"
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "__generated__"]
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "alabaster"
+html_static_path = ["images"]
+html_theme_options = {
+    "logo": "databricks-logo.svg",
+    "github_user": "databricks",
+    "github_repo": "databricks-bundles",
+    "description": "databricks-bundles: Python support for Databricks Asset Bundles",
+    "fixed_sidebar": "true",
+    "logo_text_align": "center",
+    "github_button": "true",
+    "show_related": "true",
+    "sidebar_collapse": "true",
+}
+
+python_maximum_signature_line_length = 20
+
+add_module_names = False
+python_use_unqualified_type_names = True
+
+# we include all classes by hand, because not everything is documented
+autosummary_generate = False
+
+autodoc_default_options = {
+    "members": True,
+    "member-order": "bysource",
+    "undoc-members": True,
+}
+
+autoclass_content = "class"
+
+toc_object_entries = False
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3.10", None),
+}

experimental/python/docs/databricks.bundles.core.rst

@@ -0,0 +1,41 @@
+Core
+===============================
+
+.. currentmodule:: databricks.bundles.core
+
+**Package:** ``databricks.bundles.core``
+
+.. comment:
+    We don't use automodule to manually order the classes,
+    and ensure that every class is documented well before
+    adding it to the documentation.
+
+Classes
+-----------
+
+.. autoclass:: databricks.bundles.core.Resources
+.. autoclass:: databricks.bundles.core.Resource
+.. autoclass:: databricks.bundles.core.ResourceMutator
+.. autoclass:: databricks.bundles.core.Bundle
+.. autoclass:: databricks.bundles.core.Variable
+.. autoclass:: databricks.bundles.core.Diagnostics
+.. autoclass:: databricks.bundles.core.Diagnostic
+.. autoclass:: databricks.bundles.core.Location
+.. autoclass:: databricks.bundles.core.Severity
+
+.. class:: T
+
+    :class:`~typing.TypeVar` for variable value
+
+Methods
+-----------
+
+.. automethod:: databricks.bundles.core.load_resources_from_current_package_module
+.. automethod:: databricks.bundles.core.load_resources_from_module
+.. automethod:: databricks.bundles.core.load_resources_from_modules
+.. automethod:: databricks.bundles.core.load_resources_from_package_module
+
+Decorators
+-----------
+.. autodecorator:: databricks.bundles.core.job_mutator
+.. autodecorator:: databricks.bundles.core.variables

experimental/python/docs/databricks.bundles.jobs.rst

@@ -0,0 +1,11 @@
+Jobs
+===============================
+
+.. currentmodule:: databricks.bundles.jobs
+
+**Package:** ``databricks.bundles.jobs``
+
+Classes
+---------------
+
+.. automodule:: databricks.bundles.jobs