Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: slackapi/bolt-python
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: main
Choose a base ref
...
head repository: slackapi/bolt-python
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: griff2md
Choose a head ref
Checking mergeability… Don’t worry, you can still create the pull request.
  • 2 commits
  • 499 files changed
  • 2 contributors

Commits on Aug 28, 2026

  1. docs: generate API reference as Docusaurus MDX via griffe2md 

    Replace the pdoc3 -> standalone-HTML flow with griffe2md-generated
Docusaurus MDX: one Markdown page per module under docs/english/reference
(234 pages), so the API reference flows through the same ingestion path as
the concept guides and becomes a navigable, first-class part of the docs
site instead of a hand-served HTML island.

- scripts/generate_api_docs.py: thin Docusaurus adapter around griffe2md.
  griffe loads the package (resolve_aliases=True so __all__ re-exports
  render) and parses Google docstrings; griffe2md renders Markdown in its
  default style. Post-processing fences indented docstring code and escapes
  MDX-hazardous characters in prose only, leaving code spans verbatim. A
  hazard gate fails generation on any unfenced ESM/JSX at column zero.
- scripts/generate_api_docs.sh: rewritten to install requirements/docs.txt
  and run the generator (no pdoc3, no HTML flatten dance).
- requirements/docs.txt: pinned griffe2md + griffelib, docs-build-only. The
  core runtime dependency stays slack_sdk only.
- docs/english/_sidebar.json: Reference is now an autogenerated category
  reading tools/bolt-python/reference (was a hardcoded external HTML link).
- CI: add a docs-reference drift job that regenerates and git-diffs the
  committed tree so it can never fall out of sync with the source.
- Delete the 234 committed pdoc3 .html files under docs/reference.
- Fence a few adapter docstring examples (falcon, wsgi, asgi) that used
  informal indentation / "# Python" labels so they render as code.

Verified: hazard gate reports 0 hazards; the slackapi/docs Docusaurus site
builds all 234 reference pages; format/lint/mypy and the falcon/wsgi/asgi
adapter tests pass.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
    @WilliamBergamin Claude
    WilliamBergamin and Claude committed Aug 28, 2026
    Configuration menu
    Copy the full SHA
    0d252cb View commit details
    Browse the repository at this point in the history

  2. test: enforce docstring MDX-safety at the source with an ast test 

    The API reference generator renders every slack_bolt docstring to
Docusaurus MDX. An unfenced code example is an MDX build hazard: a
column-zero `import`/`export` parses as ESM and `<...>` as JSX, either
of which aborts the docs build.

Previously the generator guarded this at render time via a
`_check_mdx_hazards()` gate over the produced Markdown. Replace that
runtime gate with a static, tool-agnostic guard at the source:

- Add tests/docstring/test_docstring_syntax.py: walks every slack_bolt
  docstring with `ast` (no imports, no optional deps) and fails on an
  unfenced code example or raw HTML tag. Robust Python signals fire even
  inside Google sections; the indent-after-blank heuristic is suppressed
  inside recognized section bodies to avoid false positives.
- Fence the code examples in 19 source docstrings so the invariant holds
  (ruff docstring-code-format then normalizes the fenced Python).
- Remove `_check_mdx_hazards()` and `_MDX_ESM_RE` from
  scripts/generate_api_docs.py; the test now owns the invariant.
- Regenerate docs/english/reference (interior code reformatted to match).

Verified: 0 MDX hazards and 0 residual HTML tags in the generated tree;
format, lint, mypy, and the affected tests pass.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>
    @WilliamBergamin Claude
    WilliamBergamin and Claude committed Aug 28, 2026
    Configuration menu
    Copy the full SHA
    07782e2 View commit details
    Browse the repository at this point in the history
Loading