You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Right now, in-tree tags documentation is duplicated in Readme.md and each tag source file docstring. As is usually a case for duplicated content, of course it has diverged over time
There are 18 or 19 tags in tree (depending if you count "generic" as real tag), but 13 listed in Readme. Which means that 5 tags are hard to discover and require reading source file to understand how they work
docstrings often do better work at documentation, by providing more examples and example HTML output
sometimes Readme provides better documentation, like in youtube tag (where Readme explains YOUTUBE_THUMB_ONLY and YOUTUBE_THUMB_SIZE variables)
This issue can be closed when we have single source of truth for all tags documentation, and that documentation is up to date.
Personally I would explore generating all docs from docstrings using sphinx, and creating readthedocs account to store that, but I am open to other solutions, too.
The text was updated successfully, but these errors were encountered:
@mirekdlugosz: Many thanks for submitting this issue. I just realized that Graphviz is a supported tag, even though it's not mentioned in the README, and then I came across this issue pointing out the general tag documentation disconnect.
I agree that it would be preferable to have the documentation up-to-date and available in single-source-of-truth form. Would anyone like to help out by starting the documentation process? I suggest we use a combination of Sphinx + MyST + Furo (latter is a modern Sphinx theme that supports and recommends MyST).
Right now, in-tree tags documentation is duplicated in Readme.md and each tag source file docstring. As is usually a case for duplicated content, of course it has diverged over time
YOUTUBE_THUMB_ONLY
andYOUTUBE_THUMB_SIZE
variables)This issue can be closed when we have single source of truth for all tags documentation, and that documentation is up to date.
Personally I would explore generating all docs from docstrings using sphinx, and creating readthedocs account to store that, but I am open to other solutions, too.
The text was updated successfully, but these errors were encountered: