sphinx-design
sphinx-design copied to clipboard
comments inside a grid generate confusing warnings
Describe the bug
context When I add a comment, either HTML or % style, inside a grid element that uses cards, I get a confusing build warning from Sphinx.
expectation I expected a clean build without warnings. Removing the comment results in no warnings.
bug Here's an error message I ran into...
WARNING: All children of a 'grid-row' should be 'grid-item' [design.grid]
Reproduce the bug
Sample markdown file:
# test grid comments
## this grid works, no comment
::::{grid} 1 2 3 4
:gutter: 3
:::{grid-item-card} AWS app
:::
::::
## this grid gives warning, html comment
::::{grid} 1 2 3 4
:gutter: 3
<!-- foo -->
:::{grid-item-card} AWS app
:::
::::
## this grid gives warning, % comment
::::{grid} 1 2 3 4
:gutter: 3
% foo
:::{grid-item-card} AWS app
:::
::::
Warnings from RTD build log
reading sources... [ 99%] content/workspaces/SearchBookmarksNotifications
reading sources... [ 99%] content/workspaces/apps
reading sources... [100%] index
/home/docs/checkouts/readthedocs.org/user_builds/observe-observe-docs/checkouts/test-grid-bug/docs/content/integrations/index.md:18: WARNING: All children of a 'grid-row' should be 'grid-item' [design.grid]
/home/docs/checkouts/readthedocs.org/user_builds/observe-observe-docs/checkouts/test-grid-bug/docs/content/integrations/index.md:26: WARNING: All children of a 'grid-row' should be 'grid-item' [design.grid]
looking for now-outdated files... none found
pickling environment... done
List your environment
Built with ReadTheDocs.com, Sphinx requirements.txt:
sphinx==5.1.1
six>=1.10.0
myst-parser==0.18.0
furo==2022.06.21
sphinx-copybutton>=0.3.1
sphinx-inline-tabs==2020.10.19b4
sphinx-design==v0.2.0
Pygments>=2.10.0
Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:
I think % comments should work (they should just be ignored when rendering), but HTML comments don't make as much sense. Supporting that is similar effort to supporting arbitrary HTML between grid-item's, which is deliberately unsupported.