Proper documentation (Diátaxis) (#42)#43
Merged
Conversation
Co-authored-by: Cursor <cursoragent@cursor.com>
Add docs/ with tutorial, how-to guides, reference, and explanation; slim the README to an overview that links into those sections; and add docstrings on the public API so reference and source stay aligned. Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
Add mkdocs.yml, requirements-docs.txt, and a Pages workflow that builds on PRs and deploys on master. Sync axis diagrams into docs/assets and point example links at GitHub so mkdocs --strict builds cleanly. Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
Add a restricted Verify docs Action that runs the Cursor CLI against Diátaxis guidelines on PRs, with sticky PR comments and a failing check when updates are needed. Expand Deploy docs so PRs always build and workflow_dispatch can deploy from this branch before merge. Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
Allow the Verify docs workflow to succeed on this branch with a PR notice when the secret is missing, so Deploy docs and Verify docs can both be exercised before the key is configured. Co-authored-by: Liron Ilouz <ilouzl@users.noreply.github.com>
Docs check
|
Headless agent exits on workspace trust prompt in GitHub Actions. Also drop Diátaxis/CI mentions from published docs per review. Co-authored-by: Cursor <cursoragent@cursor.com>
Move restrictive agent permissions to .github/docs-verify-cli.json and copy into .cursor/cli.json only during the CI job so local agent CLI runs in this repo are unaffected. Co-authored-by: Cursor <cursoragent@cursor.com>
ilouzl
marked this pull request as ready for review
July 22, 2026 09:12
ilouzl
marked this pull request as draft
July 22, 2026 09:13
Resolve Readme conflict by keeping the Diátaxis overview and porting get_device_info documentation into docs/reference. Co-authored-by: Cursor <cursoragent@cursor.com>
Stop overwriting committed docs/assets images, post agent comments via body files to avoid shell injection, and run verify-docs on docs/* branches. Co-authored-by: Cursor <cursoragent@cursor.com>
ilouzl
marked this pull request as ready for review
July 22, 2026 09:22
Post a new PR comment on each failed run (with workflow link) instead of silently updating the old one. Tighten the agent prompt and CLI permissions so missing files are reported only after git ls-files/test verification. Co-authored-by: Cursor <cursoragent@cursor.com>
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.
Closes #42
Restructures Tap Python SDK docs using the Diátaxis framework (via the documentation-writer skill), publishes them with MkDocs Material to GitHub Pages, and verifies docs on PRs with a Cursor CLI GitHub Action.
Documentation content
docs/Diátaxis quadrants (tutorial, how-to, reference, explanation)Readme.mdlinking intodocs/.cursor/rules/diataxis-docs.mdc+.cursor/cli.jsonfor agent verificationWorkflows — already running on this PR
mkdocs build --strict✅cursor/proper-documentation-b364, deploy=true)gh secret set CURSOR_API_KEY --repo TapWithUs/tap-python-sdk, then re-run Verify docs (or push any docs change)Site URL after deploy: https://tapwithus.github.io/tap-python-sdk/
Checks
flake8/pytest— passmkdocs build --strict— pass on PRCURSOR_API_KEYexists)