Libdoc dev fixtures - #5796
Libdoc dev fixtures#5796aaltat wants to merge 5 commits into
Conversation
pekkaklarck
left a comment
There was a problem hiding this comment.
Looks good except for somewhat confusing docs/comments about why fenced code blocks don't work inside admonitions.
| > Keyword | ||
| > | ||
| > Fenced code blocks do not, because fences are handled by a preprocessor | ||
| > that runs before admonitions are parsed: |
There was a problem hiding this comment.
It's true that fenced code blocks don't work inside admonitions, but I'm not entirely sure is the explanation correct and I consider it unnecessary in general. Something like this would be better:
Python-Markdown's Fenced Code Block plugin only supports fenced code blocks at the document root level.
Because this is a technical limitation in the underlying tool, I'm not sure do we actually need to test it here at all. Perhaps the test acts as a reminder that we may at some point consider using another plugin or otherwise handling this.
| ... admonitions are parsed, so a fence inside one is never | ||
| ... seen and its content ends up as an inline code span. | ||
| ... This test documents the current behavior, not a decision | ||
| ... that it is correct. |
There was a problem hiding this comment.
See my comment to MarkdownFormat.py why I consider this documentation confusing. The same doc that I proposed there, or a variation of it, would work here as well.
The Markdown acceptance tests covered admonitions holding paragraphs, a list and a nested admonition. Tables and code blocks were not covered, so changes to how either renders inside an admonition went unnoticed. Also pin the fenced code block behavior. Python-Markdown's Fenced Code Block plugin only supports fenced code blocks at the document root level, so a fence inside an admonition is not recognized and its content ends up as an inline code span instead. The limitation is documented in the User Guide, and the test is a reminder in case the plugin is ever replaced. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The development fixture covered Markdown only, because DevLibrary.py uses that format and a library has just one. The documentation tables that are hardest to style come from the ROBOT format, though, so the shapes most likely to break were the ones nothing rendered. Add DevLibraryRobotFormat.py alongside it, covering a data table with a header row, a wide table used to lay Robot data out in columns, a ragged table whose short rows Libdoc pads with empty cells, and a table too wide for the documentation column. ROBOT is the default documentation format, so tables like these are common in third-party libraries. Generating now loops over FIXTURES rather than one hardcoded library, the development server regenerates only the fixture whose library was saved, and libdoc.html picks between them: `?fixture=robot` renders the new one. Both imports are written out, because Parcel resolves them statically, and both are still stripped from production builds. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
DevLibrary.py mixed two naming conventions. Most keywords were named as a browser library would name them, while All Argument Kinds was named after the case it covers, because no real keyword has every argument kind. The fiction was never load-bearing: the library is not shipped, is used by no test, and nothing outside it refers to a keyword name. Name them all after the case instead, so the keyword list is the case list and a rendering bug is easier to reproduce. Two use `@keyword` to keep the capital D in TypedDict, which is a case of its own. The rule in the documentation is sharpened rather than dropped: what the keywords accept and return still has to be something a real library could produce, because the point is to render what Libdoc actually receives. Restructure the "What is covered" table around cases, and fix a row that wrapped onto a second source line and so rendered as a second row with an empty cell. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
The fixture showed admonitions holding paragraphs and one nested admonition. Lists, tables and code blocks can appear in them just as easily, and nothing rendered those, so the frontend was being styled against a fraction of what an admonition can contain. The code block is indented rather than fenced. Python-Markdown supports fenced code blocks only at the document root level, so one written inside an admonition is not recognized and its content ends up as an inline code span in a paragraph. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
61daf60 to
33c581e
Compare
Every keyword in the fixture that returned something was annotated, so the shape where Libdoc is given return documentation but no return type was not rendered anywhere. It is common in practice: an author who writes a docstring is not obliged to annotate, and eighteen of the eighty-eight keywords that document a return in the standard libraries look like this. Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
33c581e to
02f0152
Compare
No description provided.