Skip to content

Libdoc dev fixtures - #5796

Open
aaltat wants to merge 5 commits into
robotframework:masterfrom
aaltat:libdoc_dev_fixtures
Open

aaltat wants to merge 5 commits into
robotframework:masterfrom
aaltat:libdoc_dev_fixtures

Conversation

@aaltat

@aaltat aaltat commented Sep 23, 2026

Copy link
Copy Markdown
Contributor

No description provided.

@pekkaklarck pekkaklarck left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good except for somewhat confusing docs/comments about why fenced code blocks don't work inside admonitions.

Comment thread atest/testdata/libdoc/MarkdownFormat.py Outdated
> Keyword
>
> Fenced code blocks do not, because fences are handled by a preprocessor
> that runs before admonitions are parsed:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

aaltat and others added 4 commits September 24, 2026 15:33
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]>
@aaltat
aaltat force-pushed the libdoc_dev_fixtures branch from 61daf60 to 33c581e Compare September 24, 2026 12:52
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]>
@aaltat
aaltat force-pushed the libdoc_dev_fixtures branch from 33c581e to 02f0152 Compare September 24, 2026 17:42

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants