Wrap inline code examples in docstrings with ```python fences so the
Markdown API reference renders them as highlighted code blocks instead of
flat prose. Changes are docstring-only; no code behavior is affected.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

…down)

Replace the pdoc3 HTML generator with pydoc-markdown so the API reference
is emitted as Markdown for docs.slack.dev/Docusaurus.

- Rewrite generate_api_docs.sh to drive the new Markdown pipeline.
- Add generate_api_docs.py, which:
  - inlines re-exported classes/functions so adapter pages show their
    handler inline (matching pdoc3's behavior);
  - adds OrderedGoogleProcessor to keep fenced code blocks in their
    original position (the stock GoogleProcessor relocates a code block
    that precedes a section keyword to after the prose);
  - replaces pydoc-markdown's escape_except_blockquotes, which corrupts
    docstrings with >10 code spans by duplicating a code block into later
    spans (BLOCKQUOTE_TOKEN prefix collision).
- Regenerate docs/reference as Markdown (removes the old HTML tree).
- Point the sidebar "Reference" link at the new Markdown path.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

Rename each generated package __init__.md to index.md and rewrite the
generated sidebar.json edges to match. The docusaurus renderer emits a
package's docs as <pkg>/__init__.md, whose route is .../<pkg>/__init__ --
nothing resolves at the bare .../<pkg>/ URL that the sidebar's Reference
link (.../reference/slack_bolt/) targets. Docusaurus serves index.md at
the folder URL, so this makes that link resolve instead of 404.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

The App.start() docstring had an indented (unfenced) code example whose
'#' comment lines rendered as Markdown H1 headers in the Markdown output.
Wrap it in a ```python fence. This propagates to all 24 pages that inline
App via re-export.

Also point the generator at docs/english/reference (the reference tree's
location) instead of docs/reference.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>

The docs site imports docs/english/_sidebar.json and filters it; it does
not read the generated reference/sidebar.json. Replace the external
"Reference" link with the generated category tree, prefixing doc IDs with
tools/bolt-python/ so they resolve against the docs root.

The generator now does this automatically (_sync_reference_sidebar) so the
sidebar stays in sync on every regeneration.

Co-Authored-By: Claude <svc-devxp-claude@slack-corp.com>