Integrate your doxygen-generated technical documentation into Sphinx

These details have not been verified by PyPI

Project links

Project description

Docleaf

Your technical docs, beautifully integrated

Docleaf 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.

License

Docleaf is licensed under the Parity 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.

For further information please email: support@docleaf.io

Features

Custom 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.
Integration with the sphinx.ext.linkcode extension to support links to source code locations in a GitHub repository.

Installation

Docleaf can be installed from PyPI:

pip install docleaf

Usage

Include docleaf.doxygen as an extension in your Sphinx conf.py file:

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:: ExampleStruct

See below for available directives.

Directives

Generate documentation for a C++ class.

.. doxygenclass:: ClassName

Generate documentation for a C or C++ struct.

.. doxygenstruct:: StructName

Generate documentation for a C or C++ function.

.. doxygenfunction:: function_name

Generate documentation for a C or C++ enum.

.. doxygenenum:: EnumName

Generate documentation for specific group as specified within your Doxygen set up and code comments.

.. doxygengroup:: group_name

All directives take a :project: option to specify the project to use from your conf.py if you don't want to use the default project.

Settings

docleaf_projects

A Python dictionary mapping each project name to the folders where its source code and Doxygen XML output are stored.
docleaf_default_project

The default project to use when none is specified on the directive itself.
docleaf_domain_by_extension

A 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 .hpp will be considered as C++ files and processed using the C++ Sphinx domain whilst files that end in .h will be considered C files and processed with the C Sphinx domain.
docleaf_doxygen_skip

A 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 the htmlonly node.

Integration with `sphinx.ext.linkcode`

Docleaf can integrate with the sphinx.ext.linkcode extension 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 the sphinx.ext.linkcode extension to the extensions list in your Sphinx conf.py and use the docleaf.doxygen.GitHubLinkResolver with 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:

root is the relative path to the root of your repository.
user is the user or organisation name for your GitHub repository.
repo is the name of your GitHub repository.
tag is the git tag that you would like the generated link URLs to target.
branch is the git branch that you would like the generated link URLs to target.
commit is the git commit SHA that you would like the generated link URLs to target.

Only one of tag, branch and commit is necessary.

Performance

When 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 runs

Benchmark: 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 runs

History

Docleaf is written and maintained by the creator of the Breathe project. It was created to resolve some of the performance and memory consumption issues with Breathe by re-writing the code base to use Rust. The user experience is designed to match and improve on Breathe.

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

0.8.3

Aug 4, 2023

0.8.2

Jul 13, 2023

0.8.1

Jul 3, 2023

0.8.0

Jun 22, 2023

0.7.0

Jun 22, 2023

0.6.0

Jun 21, 2023

0.5.0

Jun 18, 2023

This version

0.4.0

Jun 14, 2023

0.3.0

Jun 10, 2023

0.2.0a0 pre-release

Jun 5, 2023

0.1.0a2 pre-release

Jun 5, 2023

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

docleaf-0.4.0-cp311-none-win_amd64.whl (1.1 MB view details)

Uploaded Jun 14, 2023 CPython 3.11 Windows x86-64

docleaf-0.4.0-cp311-none-win32.whl (995.6 kB view details)

Uploaded Jun 14, 2023 CPython 3.11 Windows x86

docleaf-0.4.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.11 manylinux: glibc 2.17+ x86-64

docleaf-0.4.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.11 manylinux: glibc 2.5+ i686

docleaf-0.4.0-cp311-cp311-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (2.6 MB view details)

Uploaded Jun 14, 2023 CPython 3.11 macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

docleaf-0.4.0-cp311-cp311-macosx_10_7_x86_64.whl (1.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.11 macOS 10.7+ x86-64

docleaf-0.4.0-cp310-none-win_amd64.whl (1.1 MB view details)

Uploaded Jun 14, 2023 CPython 3.10 Windows x86-64

docleaf-0.4.0-cp310-none-win32.whl (995.6 kB view details)

Uploaded Jun 14, 2023 CPython 3.10 Windows x86

docleaf-0.4.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.10 manylinux: glibc 2.17+ x86-64

docleaf-0.4.0-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.10 manylinux: glibc 2.5+ i686

docleaf-0.4.0-cp310-cp310-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (2.6 MB view details)

Uploaded Jun 14, 2023 CPython 3.10 macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

docleaf-0.4.0-cp310-cp310-macosx_10_7_x86_64.whl (1.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.10 macOS 10.7+ x86-64

docleaf-0.4.0-cp39-none-win_amd64.whl (1.1 MB view details)

Uploaded Jun 14, 2023 CPython 3.9 Windows x86-64

docleaf-0.4.0-cp39-none-win32.whl (995.5 kB view details)

Uploaded Jun 14, 2023 CPython 3.9 Windows x86

docleaf-0.4.0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.9 manylinux: glibc 2.17+ x86-64

docleaf-0.4.0-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.9 manylinux: glibc 2.5+ i686

docleaf-0.4.0-cp39-cp39-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (2.6 MB view details)

Uploaded Jun 14, 2023 CPython 3.9 macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

docleaf-0.4.0-cp39-cp39-macosx_10_7_x86_64.whl (1.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.9 macOS 10.7+ x86-64

docleaf-0.4.0-cp38-none-win_amd64.whl (1.1 MB view details)

Uploaded Jun 14, 2023 CPython 3.8 Windows x86-64

docleaf-0.4.0-cp38-none-win32.whl (995.6 kB view details)

Uploaded Jun 14, 2023 CPython 3.8 Windows x86

docleaf-0.4.0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.8 manylinux: glibc 2.17+ x86-64

docleaf-0.4.0-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.8 manylinux: glibc 2.5+ i686

docleaf-0.4.0-cp38-cp38-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (2.5 MB view details)

Uploaded Jun 14, 2023 CPython 3.8 macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

docleaf-0.4.0-cp38-cp38-macosx_10_7_x86_64.whl (1.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.8 macOS 10.7+ x86-64

docleaf-0.4.0-cp37-none-win_amd64.whl (1.1 MB view details)

Uploaded Jun 14, 2023 CPython 3.7 Windows x86-64

docleaf-0.4.0-cp37-none-win32.whl (995.5 kB view details)

Uploaded Jun 14, 2023 CPython 3.7 Windows x86

docleaf-0.4.0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.7m manylinux: glibc 2.17+ x86-64

docleaf-0.4.0-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.whl (2.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.7m manylinux: glibc 2.5+ i686

docleaf-0.4.0-cp37-cp37m-macosx_10_9_x86_64.macosx_11_0_arm64.macosx_10_9_universal2.whl (2.5 MB view details)

Uploaded Jun 14, 2023 CPython 3.7m macOS 10.9+ universal2 (ARM64, x86-64) macOS 10.9+ x86-64 macOS 11.0+ ARM64

docleaf-0.4.0-cp37-cp37m-macosx_10_7_x86_64.whl (1.3 MB view details)

Uploaded Jun 14, 2023 CPython 3.7m macOS 10.7+ x86-64

File details

Details for the file docleaf-0.4.0-cp311-none-win_amd64.whl.

File metadata

Download URL: docleaf-0.4.0-cp311-none-win_amd64.whl
Upload date: Jun 14, 2023
Size: 1.1 MB
Tags: CPython 3.11, Windows x86-64
Uploaded using Trusted Publishing? No
Uploaded via: twine/4.0.2 CPython/3.9.16

File hashes

Hashes for docleaf-0.4.0-cp311-none-win_amd64.whl
Algorithm	Hash digest
SHA256	`59d5a21c4c9d3545ae7baa3a4c5a194236a6b1ed0a228a0c426524a46edd562d`
MD5	`72028fc6a30c142e5b7eafb61585200e`
BLAKE2b-256	`5df8adb0d9e87ba315f81c153e5cfaedb7890710c421992b4326ef8f87c0316a`

Algorithm	Hash digest
SHA256	`59dc7358edd06f3555f14424d83f41d2849714528ab40b210a2ec36baac10228`
MD5	`d7c61ae13e90171d18be60e1c17a1662`
BLAKE2b-256	`1c454b2cd05289a0290e269764b6747cc9b63d481aeff3a30560f53d8a2f5d6a`

Algorithm	Hash digest
SHA256	`7256511982c82d3b2f71b1926bb31d491154a5ce7ec4466c8cdc27141f273bbe`
MD5	`ee111235cd32c16a2096038989a4e9c0`
BLAKE2b-256	`934b769d7ceee774ea74785b6a5a6e49877ee483a5e85b4a2262d46cd2ae952b`

Algorithm	Hash digest
SHA256	`5c81f2f78a50d7d12805445fb72558aa0d65088d5f3938b8127c60c3348985a6`
MD5	`9467b552a7bb99257cb698da52bbd02c`
BLAKE2b-256	`22bb4db39af18b46c576a94927ce0718f265b31ed246772c7f83596db96e597c`

Algorithm	Hash digest
SHA256	`a606bed3e15b61cc3107c82ee9e540b3db3cd12d80d84acde69879f73ef9ba42`
MD5	`7fe387ef1eb15e1d9729966c54c9c1a0`
BLAKE2b-256	`d4421e6e94b9484516c5b20ec73fbf4600e1e6cf3dd489570e1d321e632d4144`

Algorithm	Hash digest
SHA256	`90f96e0647efde99b196f0680c849427db7abd614d59453984cafd1bba235018`
MD5	`1dbeab0ac0e12ad13f9e18385b855bb1`
BLAKE2b-256	`5f946d02baca8159942620d243a2e144040673a61a74401151cc9209e0f8eaea`

Algorithm	Hash digest
SHA256	`e6697ac3e1594c3a78616bee679d23cfd272d0a274882b1292c2ba2a0892b98d`
MD5	`4945b80a2b95a97a98eb66678ba9852e`
BLAKE2b-256	`b2a27b4d9381029277edfd04111a8159535ee604907a49f065eac912b1ae3187`

Algorithm	Hash digest
SHA256	`f9090210ee9da4c492f0890f67bc9ac4a37d6326193931a3116aeee66e9fc13d`
MD5	`30b8a7f8f3fa003435b277d345cedad6`
BLAKE2b-256	`1ffce1382c27bfa8b43578130edf1869d47908dc257276c4d8b96b91c14e5004`

Algorithm	Hash digest
SHA256	`0333408b20f0636b357ef717bda58697d905a571cbcf7dd21682964c37de9c12`
MD5	`adedddae1fae58d515d0d2627f4687bf`
BLAKE2b-256	`7cdd15a5e41eacc6e994b227574ab4dbef0f3ed3d8fbb6980117c24197399566`

Algorithm	Hash digest
SHA256	`87e0e5b2e7c7fb85c934423dd1e5a0daa4da7f2313dd8612c3e78f96ace5c731`
MD5	`fcf5db1b3ac5c2dfcac9c525049ada31`
BLAKE2b-256	`5096465888cd1320836f736cd80939c7b0e7126660bb560803e292b31bc966a6`

Algorithm	Hash digest
SHA256	`ea0080fdd3ceced4d62d183c987724062ba46d5f736cfb2eeea02f9b4e4646b5`
MD5	`56f0f54c1f7637d2311396c40d9caf7e`
BLAKE2b-256	`628527655ad527b6b9b5e40e2fdeb7bbfdcd8e11412cfb96d5a5d0a684f9375e`

Algorithm	Hash digest
SHA256	`dad4398e1211466a2266c42476f127397d298227ffbc60f9ba98ec59e72991e0`
MD5	`54540d3dbc6b7617c52062ba2a1a031e`
BLAKE2b-256	`15d0e6e4a3e9ebba497faab0aaac26f043593bcd69bea02dc77fa42db896e867`

Algorithm	Hash digest
SHA256	`12fcc0a670ad53657579573b93e11ed967270b9a235f6523f1adf02fd7dc94df`
MD5	`035b0e392c1a93f1b016c09f73ebb72f`
BLAKE2b-256	`f86907fe68486b977a80a307ecb3a6af72579181a652354335371b23bdd0d5fe`

Algorithm	Hash digest
SHA256	`7f9b59f60a0468b741c62f446b45fbe2a7c797d5409fcac6d06e938495768c61`
MD5	`163319efe9707bfb0b45b0bb3a580f4e`
BLAKE2b-256	`66986788e138c291cb4faa7892c1847defd104c478ebe24ad9def55f5b60c5a1`

Algorithm	Hash digest
SHA256	`2e30662926222740020541da5766d9ccc8b66676008f49265d1499c5ad339dd1`
MD5	`75d64387d6e4b9d528f1a8ae57358be5`
BLAKE2b-256	`1131c9f296058a04bd121c4ae0d4d238617d6d3206dbfb8bfaddba661e146bc9`

Algorithm	Hash digest
SHA256	`628c694f505327ee6bcf7a15de4465b66e1184d48dc21416402e9118cf6d5464`
MD5	`2d2fe4027b561fabbb4ed7330fc72ecb`
BLAKE2b-256	`bc54c44acfb5c8bf198cda3ee273612015a60eec2f97ab56219c6548208261ce`

Algorithm	Hash digest
SHA256	`704e8431a44c2eea8d115ddba84c695de4977fb715138079349fbd10309688e3`
MD5	`de3c9d3d95700c8389833e013473aae9`
BLAKE2b-256	`28028f61c01da84855b5714891d9ff9808667797849578b64b07b37c3bd94664`

Algorithm	Hash digest
SHA256	`526d9e0ae7451374521796d068df6738c25ff22342a353b1eade06cec6d9cd80`
MD5	`cbc15d9d12f836fd5419d8fbb7ee3074`
BLAKE2b-256	`bdc2ac2fbb85d69ab93930381865a61e502bc728581cd00c4e084261f30389cf`

Algorithm	Hash digest
SHA256	`63628cd864009712e4c41fca5255b077ad0aed66771b5859bcd6f4e647099418`
MD5	`99054f83624be77ac016ad474161c2c7`
BLAKE2b-256	`863fb2671b6c068d015fb3a96f93f01620ab09916f78bd2b78171fd8645b0450`

Algorithm	Hash digest
SHA256	`f0f282c710903ffa40798e7ad9c383b6c7762815e95cdcd93491beb812347235`
MD5	`7ba75e47951c0d36bc28cbdaaa12326e`
BLAKE2b-256	`42d0ebcaf3201c642aff7561202f44f175fac6e5d19caea0a650453f7d40609f`

Algorithm	Hash digest
SHA256	`0491bfeee4dc18733a20ca50c256e3d5cbf23df42b84df77cdf54ee85f78d1b0`
MD5	`48605f75f68ba0cdb728a8ffe9c1fcbc`
BLAKE2b-256	`d9b35e1e2127e97380c19832fa644a171dcebffe2ade7f3f283875d829fb26ff`

docleaf 0.4.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Docleaf

License

Features

Installation

Usage

Directives

Settings

Integration with sphinx.ext.linkcode

Performance

History

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distributions

Built Distributions

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

File details

File metadata

Integration with `sphinx.ext.linkcode`

Algorithm	Hash digest
SHA256	`046745ebb4b9f246002544b97583cf272ba3e08d6d5154f84ee99681e91ec598`
MD5	`6daa98038c800f01ef1d0ac60f8c3d4c`
BLAKE2b-256	`f736005fd5d6ed083723bf279eaae29d0326c7e7aa0fe53486c2e3c71cc6b5b9`

Algorithm	Hash digest
SHA256	`b755d303defe50060ad494a4a81ac388e44c8ae93cb7d5380cba9db7381e554d`
MD5	`4b78fc3f4f32d959557a41dce73fa6f4`
BLAKE2b-256	`cc0d3ead72794e5ecd69627b691eed29dd8ba4591a254ea2f2c311a3968c70dc`

Algorithm	Hash digest
SHA256	`84f7f94f607d34373e37e9569847d0c9a39e7a6a00c287bae8603f9f9f28af2a`
MD5	`de23a30b4e50b658dd8962df8a7fb3d1`
BLAKE2b-256	`c0a02e79e84ec23c72c49f16ccb5fd791054997c67827d40e8a7a7658be49f15`

Algorithm	Hash digest
SHA256	`32ba5c056474109838409355d28f0acf5ac377d2fbdeabb4de9054372c739983`
MD5	`6ba93fece00dc03de71d6403e02ed033`
BLAKE2b-256	`1d0be0594398b80d6b163ed807a21700f32b4a12bd187d150cb2e02640b05933`

Algorithm	Hash digest
SHA256	`b3db1417a6bd723fe1f2076d88eb0d9183f9b495967ec4a996c5d846e8bed6ab`
MD5	`3942dee7e6ec2686172342a973ebb122`
BLAKE2b-256	`e8ec5a3d5f76dbffd46b758720c14b03c953aa9d987d2891feca29db07fbde6e`

Algorithm	Hash digest
SHA256	`ef192648664dd73058de31ae4b1cdf9b33559864d049a1a141404418fa880421`
MD5	`e131180e7368c706fe60cdb80d5a68ca`
BLAKE2b-256	`72431b7275c90b8044cad1eb71398345de931c111993f665dea4136df3cb6b0c`

Algorithm	Hash digest
SHA256	`b4ed8b84a1de96f31b45aac4d8614563221bedd6e5a63a7574dcce9644846f8a`
MD5	`a88f63f28bced8b679817d245bdc5ca4`
BLAKE2b-256	`34c2f7a656e569c085fc2b9b334e8f4a8a54f44c190c31b708c2fefcbd04a55d`

Algorithm	Hash digest
SHA256	`d59de3a8ac166b247cf21178e7b28f2839ac7f64e773271ff6e3f0c528187606`
MD5	`7e5e18f1cc71332eec7bdb46864c666b`
BLAKE2b-256	`c84188eaf0a597d5d9a2058415075362baf075dff55e397d7dbb1f6d4851eb79`

Algorithm	Hash digest
SHA256	`85e61d3dc3adfffa345db59901c965b26263e0bc3edbb73c22d584128a6a7bc0`
MD5	`9a174637c4d1ba392dfba00202098644`
BLAKE2b-256	`db2332f5393822760dd62d09e2aa9b44d139481e4c90f496507e69dba917b86e`