ci: introduce markdownlint-cli2 and verify docs build on PRs#718
Merged
Conversation
…717) Lint Markdown under docs/ and project-root *.md, and run sphinx-multiversion build on docs-touching PRs to catch syntax/reference errors before merge. - Pin markdownlint-cli2 0.18.1 via .mise.toml (npm backend; node auto-resolved) - Add .markdownlint-cli2.jsonc tuned to existing PyAthena docs style: dash bullets, 2-space indent, allow inline HTML used in MyST/README - Add make docs-lint / docs-lint-fix targets that shell out via mise exec - Add .github/workflows/docs-lint.yaml: lint + sphinx-multiversion build, triggered only on docs/**, **.md, and the workflow/config files themselves - Fix 5 remaining manual violations after auto-fix: - MD051: use MyST {ref}`pandas-cursor` instead of broken HTML anchor - MD036: promote three bold-as-heading spans in pandas.md to h4 - MD001: add "Basic usage" h2 wrapper in sqlalchemy.md - Auto-fix touched README.md, CLAUDE.md, docs/*.md (mostly bullet style) - Document mise-based local workflow in CLAUDE.md Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Originally disabled to land the initial config without manual cleanup, but the violations are all fixable and the rules catch real Markdown smell. - MD040 (require code fence language): 0 violations after auto-fix - MD031 (blanks around fences) / MD032 (blanks around lists): fixed by --fix in docs/introduction.md, docs/sqlalchemy.md, CLAUDE.md - MD034 (no bare URLs): wrapped 4 footer URLs in README.md with <...> Remaining intentionally-disabled rules: - MD013 (line length): docs have long URLs and code lines - MD014 ($ command without output): convention in docs/testing.md, README - MD024 siblings_only: cursor docs reuse subsection names per cursor - MD041 (first line H1): MyST `(label)=` ref targets precede the first heading Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Group related targets under a common namespace for discoverability: - docs -> docs/build - (new) -> docs/lint - (new) -> docs/format - test -> test/pyathena - test-sqla -> test/sqla - test-sqla-async-> test/sqla-async Propagate the rename through pyproject.toml (tox commands), CLAUDE.md, docs/testing.md, and the docs/docs-lint GitHub workflows. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.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
1 participant
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.
WHAT
Closes #717.
.markdownlint-cli2.jsonctuned to PyAthena's existing Markdown style (dash bullets, 2-space nested indent, allow inline HTML used by README centered-image markup and MyST admonitions).markdownlint-cli2@0.18.1via.mise.tomlusing mise'snpm:backend. Nonodedeclaration needed — mise resolves it automatically..github/workflows/docs-lint.yamlthat runs on PRs touchingdocs/**,**.md,.markdownlint-cli2.jsonc,.mise.toml,Makefile, or the workflow itself. Two jobs:make docs/lint(markdownlint-cli2)make docs/build(sphinx-multiversion)/:docs→docs/build; addeddocs/lint,docs/formattest→test/pyathena;test-sqla→test/sqla;test-sqla-async→test/sqla-asyncpyproject.toml) and existing CI workflows updated to match.MD051MyST{ref}, threeMD036heading promotions in pandas.md,MD001"Basic usage" wrapper in sqlalchemy.md, 4 bare README footer URLs wrapped in<...>).MD031,MD032,MD034,MD040.CLAUDE.md.Intentionally kept disabled with rationale in
.markdownlint-cli2.jsonc:MD013(line length) — docs have long URLs and code linesMD014($without output) — intentional indocs/testing.mdand README shell snippetsMD024siblings_only: true— cursor docs reuse subsection namesMD041(first line H1) — MyST(label)=ref targets precede the first headingWHY
The docs Sphinx build currently runs only on
pushtomaster(.github/workflows/docs.yaml). Syntax errors, broken cross-references, or other build failures are only caught after merge. Markdown style also drifts across files (*/-bullets mixed, missing blanks around fences, etc.).This PR catches both classes of failure on the PR itself, and aligns existing files with one consistent style without changing rendered output.