Add support for xrefitem based page generation #596
Conversation
|
@vermeeren breathe |
|
@utzig Yeah no problem, you can disable it for now. |
Ooops, sorry, did not expect you to answer this fast! I did it now, but I'll drop the commit once the test passes (if it does!). |
utzig
force-pushed
the
xrefsect-pages
branch
2 times, most recently
from
a390e4f
to
33fe8d8
Compare
I dropped the commit disabling Sphinx git and >3.2.1 so it should fail again! |
|
Can rebase after #597 to pass again... |
When xrefitem, or its specializations, is used some extra XML elements are generated which were not properly parsed; this commit adds the extra parsing required. * properly parses a variable list element, which consists of a set of varlistentry + listitem elements * docTitleTypeSub was extended to to parse the "ref" and "anchor" elements which exist inside a varlistentry. Signed-off-by: Fabio Utzig <[email protected]>
There was a problem hiding this comment.
@utzig Finally had some proper time to review today, sorry for the delay. The directive itself, including implementation, are all good. This definitely fills in a gap of functionality, big thanks for that.
Just noticed some minor issues with the docs, can you fixup? The follow-up review will be quick and a release will be made after merging as usual.
vermeeren
added
code
When xrefitem or any of its specializations is used, Doxygen generates a new file of kind="page"; this is very similar to a "group" or "namespace" file. This commit adds proper filter handling and a new directive, doxygenpage, that can be used to include documentation from a page block. Signed-off-by: Fabio Utzig <[email protected]>
Signed-off-by: Fabio Utzig <[email protected]>
When a content block was not found, the message would imply it is of
type "namespace"; fix it so that the proper "kind" is displayed
("namespace", or "group", or "page").
Signed-off-by: Fabio Utzig <[email protected]>
The elements "docvariablelist", "docvarlistentry" and "docanchor" are used whenever an xrefitem is used in a project, and the proper compound of kind="page" is generated. This commits adds rendering of the elements in a definition block, and properly adds a target to anchor elements so they can be referenced later. Signed-off-by: Fabio Utzig <[email protected]>
Mimic Doxygen html output, by adding a pending_xref to xrefitem titles, which can later be resolved to the generated xrefsect page, if it was added to the project. Signed-off-by: Fabio Utzig <[email protected]>
Add initial documentation with "doxygenpage" usage relying on previously added xrefsect examples. Signed-off-by: Fabio Utzig <[email protected]>
utzig
force-pushed
the
xrefsect-pages
branch
from
50ad412
to
6830f3f
Compare
|
@vermeeren I believe all issues were fixed. |
Implement full support for parsing XML using xrefitem, and page blocks. Add a new directive, "doxygenpage", for rendering pages that contain data that was "xrefitem"'d.
For the "doxygenpage" directive, which uses a block of kind="page", which is pretty much the same as kind="namespace" or kind="group", I decided to remove most options, but I might want "content-only" later which I'd rather add in a followup PR.
A bit of confusion might exist now that I am calling this "doxygenpage" and using examples from "xrefsect" while building the examples, which is due to the strong relation between both, but maybe the "xrefsect" example should now be renamed "page".
I am adding a very small test attached that can be built using
doxygen doxyfile && sphinx-build -b html . htmljust in case you want to see how the results look: xref_test.tar.gzAlso includes commits fixing a few issues found on the way.
PR: tests are failing on Sphinx==3.3.0 on my machine (but this is also the case for
master).