Documentation: Render and publish Doxygen documentation - #1386
Draft
mkannwischer wants to merge 4 commits into
Draft
Documentation: Render and publish Doxygen documentation#1386mkannwischer wants to merge 4 commits into
mkannwischer wants to merge 4 commits into
Conversation
Turn the Doxygen lint config into one that renders the documentation in mldsa/ to HTML. Rendering reports the same errors the previous XML-only run did, and nothing consumed that XML, so lint now checks the documentation by building it. Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
Render the documentation on every change to main and commit it to the doxygen/ directory of the gh-pages branch, next to the benchmark results. The publishing step starts over on top of the branch tip should it race with the benchmark job, which writes to the same branch. Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
Doxygen does not link macro names that appear in a documentation block. Prefix them with '#' so that the rendered documentation links to their definition, and turn the comments on the error codes into documentation blocks, which the @RetVal references now point to. The configuration options are not linked: they are commented out in the default configuration, so Doxygen does not see them. - Resolves #1313 Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
Configuration options that are off by default are commented-out #define directives, which Doxygen does not see: their documentation blocks were attached to whichever option happened to be enabled next, leaving all but two options undocumented and MLD_CONFIG_NAMESPACE_PREFIX carrying the documentation of MLD_CONFIG_FILE. scripts/doxygen-config-filter uncomments the directives on the way into the parser and undefines them again at the end of the file, so that each option is documented in its own right while headers including the configuration file keep documenting the default configuration. With the options visible, references to them can be prefixed with '#' as well. Predefining MLD_BUILD_INTERNAL exposes the build-only options, whose documentation had never been parsed; escape the '#' in the MLD_CONFIG_MONOBUILD_KEEP_SHARED_HEADERS block, which Doxygen reads as a request to link to a symbol named 'undef'. Signed-off-by: Matthias J. Kannwischer <matthias@zerorisc.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
See individual commits.