Docs: creates markdown reference - #1565
Open
lukegalbraithrussell wants to merge 21 commits into
Open
Conversation
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>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1565 +/- ##
=======================================
Coverage 91.54% 91.54%
=======================================
Files 228 228
Lines 7285 7285
=======================================
Hits 6669 6669
Misses 616 616 ☔ View full report in Codecov by Harness. |
WilliamBergamin
requested changes
Aug 19, 2026
WilliamBergamin
left a comment
WilliamBergamin
left a comment
Contributor
There was a problem hiding this comment.
Thanks for working on this 💯
Left some comments/questions before we can move forward with this 🙏
| @@ -0,0 +1,756 @@ | |||
| #!/usr/bin/env python | |||
Contributor
There was a problem hiding this comment.
This is a lot of custom code 😅 any chance we can rely on defaults or configs instead of having this?
| @@ -26,35 +26,61 @@ | |||
| class AsyncOAuthSettings: | |||
| # OAuth flow parameters/credentials | |||
| client_id: str | |||
| """Check the value in Settings > Basic Information > App Credentials""" | |||
Contributor
There was a problem hiding this comment.
I don't see these pydoc comments showing up in the generated markdown 🤔 if they are not there then I think we should not add them
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR replaces the html reference with a md-based on. Tighter integration with docusaurus, and allows easier agent access as the md files are accessible. Also will now be trackable in Google Analaytics
Testing
Category
slack_bolt.Appand/or its core componentsslack_bolt.async_app.AsyncAppand/or its core componentsslack_bolt.adapter/docsRequirements
Please read the Contributing guidelines and Code of Conduct before creating this issue or pull request. By submitting, you are agreeing to those rules.
./scripts/install_all_and_run_tests.shafter making the changes.