Skip to content

Commit 8141683

Browse files
kanterovkanterov
authored
[Python] Configure Sphinx docs (#2496)
## Changes Configure Sphinx docs for Python code. There is a lot of customization for Sphinx output to make complex type signatures readable: - Type dicts are not documented, because they exactly follow dataclass schema - Variables are excluded from type signatures After that, when the rest of the code is ready, we can automatically publish docs into gh-pages. ## Tests Adds CI check
1 parent 7c16044 commit 8141683

File tree

11 files changed

+886
-3
lines changed

11 files changed

+886
-3
lines changed

‎.github/workflows/python_push.yml‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ jobs:
3535
- name: Install uv
3636
uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
3737
with:
38-
python-version: ${{ matrix.python-version }}
38+
python-version: ${{ matrix.pyVersion }}
3939
version: "0.6.5"
4040

4141
- name: Run tests
@@ -54,8 +54,24 @@ jobs:
5454
uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
5555
with:
5656
version: "0.6.5"
57-
checksum: "8fc9895719a1291ecd193cb86f9282ff3649cef797d29eacc74c4f573aab1e2f"
5857

5958
- name: Run lint
6059
working-directory: experimental/python
6160
run: make lint
61+
62+
python_docs:
63+
name: docs
64+
runs-on: ubuntu-latest
65+
66+
steps:
67+
- name: Checkout repository and submodules
68+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
69+
70+
- name: Install uv
71+
uses: astral-sh/setup-uv@f94ec6bedd8674c4426838e6b50417d36b6ab231 # v5.3.1
72+
with:
73+
version: "0.6.5"
74+
75+
- name: Run docs
76+
working-directory: experimental/python
77+
run: make docs

‎experimental/python/.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ __pycache__/
66
*$py.class
77

88
# Sphinx
9-
_output
9+
docs/_output
1010
docs/_build/
1111

1212
# Distribution / packaging

‎experimental/python/Makefile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,10 @@ fmt:
44
uv run ruff check --fix $(sources) || true
55
uv run ruff format
66

7+
docs:
8+
# Python 3.12+ is needed for get_overloads
9+
uv run --python 3.12 sphinx-build docs docs/_output --fail-on-warning --show-traceback --nitpicky --fresh-env --keep-going
10+
711
lint:
812
# check if lock matches the project metadata
913
uv lock --check
@@ -18,3 +22,5 @@ test:
1822
build:
1923
rm -rf build dist
2024
uv build .
25+
26+
.PHONY: fmt docs lint test build

‎experimental/python/docs/conf.py‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# For the full list of built-in configuration values, see the documentation:
4+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
5+
6+
# -- Project information -----------------------------------------------------
7+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
8+
9+
import sys
10+
import os
11+
12+
sys.path.append(os.path.abspath(".."))
13+
sys.path.append(os.path.abspath("ext"))
14+
15+
16+
project = "databricks-bundles"
17+
copyright = "2024, Databricks"
18+
author = "Gleb Kanterov"
19+
release = "beta"
20+
21+
# -- General configuration ---------------------------------------------------
22+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
23+
24+
# Add any Sphinx extension module names here, as strings. They can be
25+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
26+
# ones.
27+
extensions = [
28+
"autodoc_databricks_bundles",
29+
"sphinx.ext.autodoc",
30+
"sphinx.ext.autosummary",
31+
"sphinx.ext.intersphinx",
32+
]
33+
34+
autodoc_typehints = "signature"
35+
36+
templates_path = ["_templates"]
37+
exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "__generated__"]
38+
39+
# -- Options for HTML output -------------------------------------------------
40+
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
41+
42+
html_theme = "alabaster"
43+
html_static_path = ["images"]
44+
html_theme_options = {
45+
"logo": "databricks-logo.svg",
46+
"github_user": "databricks",
47+
"github_repo": "databricks-bundles",
48+
"description": "databricks-bundles: Python support for Databricks Asset Bundles",
49+
"fixed_sidebar": "true",
50+
"logo_text_align": "center",
51+
"github_button": "true",
52+
"show_related": "true",
53+
"sidebar_collapse": "true",
54+
}
55+
56+
python_maximum_signature_line_length = 20
57+
58+
add_module_names = False
59+
python_use_unqualified_type_names = True
60+
61+
# we include all classes by hand, because not everything is documented
62+
autosummary_generate = False
63+
64+
autodoc_default_options = {
65+
"members": True,
66+
"member-order": "bysource",
67+
"undoc-members": True,
68+
}
69+
70+
autoclass_content = "class"
71+
72+
toc_object_entries = False
73+
74+
intersphinx_mapping = {
75+
"python": ("https://docs.python.org/3.10", None),
76+
}

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
Core
2+
===============================
3+
4+
.. currentmodule:: databricks.bundles.core
5+
6+
**Package:** ``databricks.bundles.core``
7+
8+
.. comment:
9+
We don't use automodule to manually order the classes,
10+
and ensure that every class is documented well before
11+
adding it to the documentation.
12+
13+
Classes
14+
-----------
15+
16+
.. autoclass:: databricks.bundles.core.Resources
17+
.. autoclass:: databricks.bundles.core.Resource
18+
.. autoclass:: databricks.bundles.core.ResourceMutator
19+
.. autoclass:: databricks.bundles.core.Bundle
20+
.. autoclass:: databricks.bundles.core.Variable
21+
.. autoclass:: databricks.bundles.core.Diagnostics
22+
.. autoclass:: databricks.bundles.core.Diagnostic
23+
.. autoclass:: databricks.bundles.core.Location
24+
.. autoclass:: databricks.bundles.core.Severity
25+
26+
.. class:: T
27+
28+
:class:`~typing.TypeVar` for variable value
29+
30+
Methods
31+
-----------
32+
33+
.. automethod:: databricks.bundles.core.load_resources_from_current_package_module
34+
.. automethod:: databricks.bundles.core.load_resources_from_module
35+
.. automethod:: databricks.bundles.core.load_resources_from_modules
36+
.. automethod:: databricks.bundles.core.load_resources_from_package_module
37+
38+
Decorators
39+
-----------
40+
.. autodecorator:: databricks.bundles.core.job_mutator
41+
.. autodecorator:: databricks.bundles.core.variables

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
Jobs
2+
===============================
3+
4+
.. currentmodule:: databricks.bundles.jobs
5+
6+
**Package:** ``databricks.bundles.jobs``
7+
8+
Classes
9+
---------------
10+
11+
.. automodule:: databricks.bundles.jobs

0 commit comments

Comments
 (0)