Package: docleaf
DocleafYour technical docs, beautifully integratedDocleaf smoothly integrates your technical and long-form documentation. It is a Sphinx extension which reads Doxygen
XML output and formats the information seamlessly with your user documentation.LicenseFeaturesInstallationUsagePerformanceHistoryLicenseDocleaf is licensed under theParity Public License. The Parity license allows permissive use of
Docleaf to help document open source projects. If you have a closed source project that you would like to document with
Docleaf then you must purchase a commercial license. Please see theDocleaf Pricingpage for more information.If you have any questions please email:support@docleaf.ioFeaturesCustom directives allowing you to target various parts of C and C++ code bases.Integration with Sphinx C and C++ domains to support easily linking to your generated output.Hash-based content checks, as well as timestamp checks, to minimize incremental build times after a Doxygen run.Integration with thesphinx.ext.linkcodeextension to support links to source code locations in a GitHub
repository.InstallationDocleaf can be installed fromPyPI:pip install docleafUsageIncludedocleaf.doxygenas an extension in your Sphinxconf.pyfile:extensions=["docleaf.doxygen"]Configure the extension to know where your source code is stored and the Doxygen XML output has been generated for
your project. Optionally set the default project:docleaf_projects={"my_project":{"root":"../src","xml":"../doxygen/xml"}}docleaf_default_project="my_project"The use the provided directives in your reStructuredText files:..doxygenstruct::ExampleStructSee below for available directives.DirectivesGenerate documentation for a C++ class...doxygenclass::ClassNameGenerate documentation for a C or C++ struct...doxygenstruct::StructNameGenerate documentation for a C or C++ function...doxygenfunction::function_nameGenerate documentation for a C or C++ enum...doxygenenum::EnumNameGenerate documentation for specific group as specified within your Doxygen set up and code comments...doxygengroup::group_nameAll directives take a:project:option to specify the project to use from yourconf.pyif you don't want to use
the default project.Settingsdocleaf_projectsA Python dictionary mapping each project name to the folders where its source code and Doxygen XML output are stored.docleaf_default_projectThe default project to use when none is specified on the directive itself.docleaf_domain_by_extensionA Python dictionary mapping from file extension to Sphinx domain. Docleaf uses Doxygen's language classifications
where possible but for optimal control of how source files are classified it is useful to use this setting. For
example:docleaf_domain_by_extension={"hpp":"cpp","h":"c"}Will make sure that all files that end in.hppwill be considered as C++ files and processed using the C++ Sphinx
domain whilst files that end in.hwill be considered C files and processed with the C Sphinx domain.docleaf_doxygen_skipA list of instructions describing any parts of the Doxygen XML to skip when generating the output documentation.
Supported entries are:members:all_caps- Skips any function or variable members (as defined as a 'memberdef' by Doxygen) which have
names which are all capital letters and underscores. This is to allow users to filter our unprocessed C/C++ macros
if desirable.xml-nodes:<node name>- Skips reading and process of the given XML node and its children in the Doxygen XML
output. Support is limited to thehtmlonlynode.Integration withsphinx.ext.linkcodeDocleaf can integrate with thesphinx.ext.linkcodeextension in order to add[source]links next to various
supported entries in your documentation. Linking to GitHub based repositories is supported.In order to use it, add thesphinx.ext.linkcodeextension to theextensionslist in your Sphinxconf.pyand use
thedocleaf.doxygen.GitHubLinkResolverwith appropriate parameters for your repository.extensions=["docleaf.doxygen","sphinx.ext.linkcode",]linkcode_resolve=docleaf.doxygen.GitHubLinkResolver(root="../../../",user="docleaf-labs",repo="docleaf",branch="main")Where:rootis the relative path to the root of your repository.useris the user or organisation name for your GitHub repository.repois the name of your GitHub repository.tagis the git tag that you would like the generated link URLs to target.branchis the git branch that you would like the generated link URLs to target.commitis the git commit SHA that you would like the generated link URLs to target.Only one oftag,branchandcommitis necessary.PerformanceWhen doing a clean build of the Zephyr RTOS documentation suite, Docleaf is 2.1x faster than Breathe.Benchmark: docleaf
  Time (mean ± σ):     180.383 s ±  3.213 s    [User: 448.242 s, System: 12.908 s]
  Range (min … max):   175.695 s … 185.187 s    10 runsBenchmark: breathe
  Time (mean ± σ):     389.658 s ±  5.271 s    [User: 1839.366 s, System: 24.895 s]
  Range (min … max):   379.093 s … 394.315 s    10 runsHistoryDocleaf is written and maintained by the creator of theBreatheproject.
It was created to resolve some of the performance and memory consumption issues with Breathe by rewriting the code
base to use Rust. The user experience is designed to match and improve on Breathe.