docs: Fix list & code block formatting on RtD#1257
Merged
RonnyPfannschmidt merged 8 commits intopypa:mainfrom Jan 24, 2026
Merged
docs: Fix list & code block formatting on RtD#1257RonnyPfannschmidt merged 8 commits intopypa:mainfrom
RonnyPfannschmidt merged 8 commits intopypa:mainfrom
Conversation
RtD's MarkDown parser doesn't recognize a new bulleted list following body text (or a parent list item) unless there's a blank line preceding the first list marker. Without the blank, the list items get run into the preceding paragraph/item text. Add blank lines to ensure lists format as lists.
for more information, see https://pre-commit.ci
Contributor
Author
|
Wow, the Mercurial tests seem impossibly slow, the CI just grinds to a halt when it hits them. |
Contributor
Author
|
Still not quite there, the run-together text is fixed but this is still wrong: 
Perhaps the unordered child items are under-indented. |
ferdnyc
commented
Jan 23, 2026
Contributor
Author
|
All now addressed, I believe. ✔️ Everything looks right to me, now, on all four pages affected. |
Add missing blank lines before/after fenced code blocks, and before the first list marker in an (un)ordered list.
Filenames for a fenced code block applied with `file="name"` weren't showing up on ReadTheDocs, but using `title="name"` instead makes them visible.
Add a type indicator for syntax highlighting to several code blocks which lacked one, and provide the name of the file for which content is represented using a `title="name"` atttr.
Add blank lines preceding (un)ordered lists and fenced code blocks, and following headings.
Add missing blank line which should precede (un)ordered lists, and follow headings.
ferdnyc
changed the title
RonnyPfannschmidt
added a commit
to RonnyPfannschmidt/setuptools_scm
that referenced
this pull request
Jan 24, 2026
Merged PRs from main: - pypa#1257: docs formatting fixes (blank lines, code blocks) - pypa#1254: file finder GIT env var sanitization fix - pypa#1256: CI windows gnupg path fix - pypa#1251: bump actions/download-artifact to v7 - pypa#1250: fix list markup in docs - pypa#1248: typo fixes (its → it's) - pypa#1237: bump actions/checkout to v6 Conflict resolutions: - python-tests.yml: kept monorepo sync command, updated to download-artifact v7 - README.md: kept clean monorepo README - docs/config.md: kept vcs_versioning.Configuration reference - _config.py, _pyproject_reading.py: applied typo fixes - _git.py: merged imports and no_git_env fix
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.
The docs' source formatting was triggering some quirks of RtD's MarkDown parser, things like:
file="name"attribute weren't showing the "name" string as the filename. Changed totitle="name", which is visible.(EDIT: It seems this is a followup of sorts to #1250, which started the process of addressing these.)
======== SCREENSHOT: Before (1) ========
2, 3, and 4 are supposed to be a bulleted list child of list item 1. The ordered list should only have two items.
======== SCREENSHOT: Before (2) ========
Each of these paragraphs is supposed to be an introductory line of text followed by a 2-item bulleted list.