docs: fix RST rendering of code blocks in toeplitz docstrings (#198)#285
Open
r1cksync wants to merge 1 commit into
Open
docs: fix RST rendering of code blocks in toeplitz docstrings (#198)#285r1cksync wants to merge 1 commit into
r1cksync wants to merge 1 commit into
Conversation
The materialize_lower_triangular and solve_banded docstrings wrapped their example ASCII matrices in Markdown triple-backtick fences. Sphinx/napoleon render docstrings as reStructuredText, where triple backticks are not a code-block syntax, so the matrices showed up with literal backtick characters and were reflowed instead of displayed as monospace blocks (issue google-deepmind#198). Convert them to RST literal blocks (a trailing "::" plus an indented block) and mark the inline `coef`/`n`/`rhs` examples as inline literals.
|
This PR has been idle for 7 days. Please provide an update or review. |
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
Addresses part of #198 (RTD formatting — item 1, "Code is not being formatted properly"). The
matrix_factorization.toeplitzdocstrings formaterialize_lower_triangularandsolve_bandedwrap their example ASCII matrices in Markdown```fences. Docstrings are rendered as reStructuredText (Sphinx + napoleon), where triple backticks are not code-block syntax, so the matrices render with literal backtick characters and get reflowed instead of shown as a monospace block (visible on thesolve_bandedRTD page cited in the issue).Fix
Convert the two fenced blocks to RST literal blocks (end the lead-in line with
::and indent the matrix), and mark the inlinecoef/n/rhsexamples as inline literals (``).Verification
Rendered both (dedented) docstrings through
docutils: each now produces exactly oneliteral_blocknode (the matrix) plus inlineliteralnodes, with no warnings introduced by the change.Per the issue ("Incremental changes to fix these up will be good"), this is scoped to the two cited functions; happy to follow up on the other sub-items (type-alias rendering, overview links) separately.