Details
-
Task
-
Status: Stalled (View Workflow)
-
Major
-
Resolution: Unresolved
-
None
Description
Developers can benefit from a comprehensive plugin API documentation.
The currently agreed way to produce this is to:
- run doxygen on the plugin API headers and a specially crafted main page file to produce XML.
- run moxygen (https://github.com/sourcey/moxygen) on the XML file.
So all we need is cmake support for the above. This is what this MDEV is about.
cmake/generated_docs.cmake adds the following:
- WITH_GENERATED_DOCS boolean cmake variable (default off) to control if the generated docs should be built at all.
- GENERATED_DOCS_FIND_PROGRAMS() macro: to look for doxygen and moxygen, set paths and fail if not found.
- GENERATED_DOCS_PROJECT function: to add a new "project" to generate. There's also a project information added to the summary at the end of cmake.
The arguments and the usage examples are documented into generated_docs.cmake.
A call to GENERATED_DOCS_FIND_PROGRAMS is added to the top level CmakeLists.txt file.
A call to GENERATED_DOCS_PROJECT for plugin_api project is added to include/ CMakeLists.txt to generate documentation for the plugins API headers.
With that, if the prerequisites (a functional doxygen and moxygen tools) are met and WITH_GENERATED_DOCS is set to true, a Markdown documentation for the Plugin API will be generated.
Note that more "projects" can be added later using the same machinery, as needed: e.g. a server source, a plugin documentation etc.
Attachments
Issue Links
- blocks
-
MDEV-39806 Add a per-push/per-pull-request checker for Markdown API docs
-
- In Review
-