{"id":16731240,"url":"https://github.com/svenevs/exhale","last_synced_at":"2025-05-16T08:04:21.667Z","repository":{"id":16092998,"uuid":"65412345","full_name":"svenevs/exhale","owner":"svenevs","description":"Automatic C++ library api documentation generation: breathe doxygen in and exhale it out.","archived":false,"fork":false,"pushed_at":"2024-08-09T12:09:01.000Z","size":1725,"stargazers_count":230,"open_issues_count":67,"forks_count":49,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-05-15T09:54:19.349Z","etag":null,"topics":["breathe","c-plus-plus","doxygen","readthedocs","sphinx-documentation"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/svenevs.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-10T19:58:27.000Z","updated_at":"2025-05-12T07:17:26.000Z","dependencies_parsed_at":"2024-10-30T14:14:05.441Z","dependency_job_id":null,"html_url":"https://github.com/svenevs/exhale","commit_stats":{"total_commits":218,"total_committers":17,"mean_commits":"12.823529411764707","dds":"0.37155963302752293","last_synced_commit":"e9e92d207715e9edb724ef8dc5b5e2cff482d361"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenevs%2Fexhale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenevs%2Fexhale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenevs%2Fexhale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/svenevs%2Fexhale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/svenevs","download_url":"https://codeload.github.com/svenevs/exhale/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254493378,"owners_count":22080126,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["breathe","c-plus-plus","doxygen","readthedocs","sphinx-documentation"],"created_at":"2024-10-12T23:36:22.088Z","updated_at":"2025-05-16T08:04:16.658Z","avatar_url":"https://github.com/svenevs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"Exhale\n========================================================================================\n|docs| |pypi| |coverage| |license|\n\n.. begin_badges\n\n.. |docs| image:: https://readthedocs.org/projects/exhale/badge/?version=latest\n   :alt: Documentation Status\n   :target: https://exhale.readthedocs.io/en/latest/?badge=latest\n\n.. |pypi| image:: https://badge.fury.io/py/exhale.svg\n   :alt: Latest Version\n   :target: https://badge.fury.io/py/exhale\n\n.. |coverage| image:: https://codecov.io/gh/svenevs/exhale/branch/master/graph/badge.svg\n   :alt: Code Coverage Report\n   :target: https://codecov.io/gh/svenevs/exhale\n\n.. |license| image:: https://img.shields.io/github/license/svenevs/exhale.svg\n   :alt: License BSD-3 Clause\n   :target: https://github.com/svenevs/exhale/blob/master/LICENSE\n\n.. end_badges\n\nAutomatic C++ library API documentation generator using Doxygen, Sphinx, and Breathe.\nExhale revives Doxygen's class, file, and page hierarchies in reStructuredText documents\nto make these hierarchies available in Sphinx documented projects.\n\n.. end_intro\n\n.. contents:: Contents\n   :local:\n   :backlinks: none\n\n.. _is_it_for_me:\n\nIs it For Me?\n----------------------------------------------------------------------------------------\n\nExhale might **not** be the tool you are looking for!  It was designed to be as\nintuitive and flexible as possible, but it does require more machinery to get\neverything started.\n\n**Why use it?**\n    You would use Exhale if you want to have beautiful Sphinx generated websites, but\n    also see the value of the Class, File, and Page hierarchies provided by Doxygen.\n    From running Doxygen for you, to organizing your full API every time, you won't need\n    to worry about your documentation getting out of sync with the code --- it's\n    regenerated on the fly every time.\n\n**Why not use it?**\n    It may be more involved than you need.  Check out the ``breathe-apidoc`` tool that\n    comes with your installation of ``breathe``.  It is quite similar to the\n    `Sphinx API doc tool \u003chttps://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html\u003e`_,\n    and that may be all you are looking for to get your documentation displayed.\n\n    If you are working with a small enough framework, you may also be satisfied with\n    just using the ``.. autodoxygenindex::`` directive from ``breathe``.  It works very\n    well!\n\n**The Main Difference**\n    The Class, File, and Page hierarchies are only available in Sphinx via Exhale 😊\n\n    Depending on the size and complexity of your project, ``breathe-apidoc`` or\n    ``autodoxygenindex`` may be more appropriate.\n\n**Important Consideration**\n    Exhale is known to work well on small to medium sized projects.  Supporting larger\n    projects in Sphinx is a much more involved process that may or may not be resolved\n    over time -- this has to do with a lot more than just Exhale, but the nature of\n    Exhale (generation of a large number of ``.rst`` files) definitely does not help.\n\nPlease see the `full documentation \u003chttps://exhale.readthedocs.io/en/latest\u003e`_ for more\ninformation on how to get started.\n\nSee it in Action\n----------------------------------------------------------------------------------------\n\nThe `ExhaleCompanion \u003ccompanion_\u003e`_ repository has three builds to demonstrate the\ndifferent options with respect to creating a Tree View, as well as details of specific\nHTML Theme choices:\n\n+------------------------------+------------------+----------------------+\n| HTML Theme Choice            | TreeView Created | ExhaleCompanion Docs |\n+==============================+==================+======================+\n| `RTD Theme \u003crtd_\u003e`_          | Yes              | |rtd-docs|           |\n+------------------------------+------------------+----------------------+\n| `Bootstrap Theme \u003cbstrap_\u003e`_ | Yes              | |bootstrap-docs|     |\n+------------------------------+------------------+----------------------+\n| `Alabaster`_                 | No               | |alabaster-docs|     |\n+------------------------------+------------------+----------------------+\n\n.. _companion:  https://github.com/svenevs/exhale-companion\n\n.. _rtd:       https://sphinx-rtd-theme.readthedocs.io/en/latest/\n.. _bstrap:    https://ryan-roemer.github.io/sphinx-bootstrap-theme/\n.. _alabaster: https://alabaster.readthedocs.io/en/latest\n\n.. |rtd-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=latest\n   :target: https://my-favorite-documentation-test.readthedocs.io/en/latest/\n\n.. |bootstrap-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=bootstrap\n   :target: https://my-favorite-documentation-test.readthedocs.io/en/bootstrap\n\n.. |alabaster-docs| image:: https://readthedocs.org/projects/my-favorite-documentation-test/badge/?version=alabaster\n   :target: https://my-favorite-documentation-test.readthedocs.io/en/alabaster\n\n\nInstallation\n----------------------------------------------------------------------------------------\n\nExhale is a `Sphinx Extension`__ that depends on `Breathe`_ for access to the Doxygen\nreStructuredText directives, and both `BeautifulSoup`_ and `lxml`_ for parsing the\ngenerated Doxygen XML documentation.  Exhale is `hosted on PyPI\n\u003chttps://pypi.org/project/exhale/\u003e`_, meaning you can install it through the normal\nmechanisms, e.g.,\n\n__ https://www.sphinx-doc.org/en/master/usage/extensions/index.html\n\n.. _BeautifulSoup: https://www.crummy.com/software/BeautifulSoup/bs4/doc/\n.. _lxml: https://lxml.de/\n.. _Breathe: https://breathe.readthedocs.io/en/latest/\n\n.. code-block:: console\n\n   $ python -m pip install exhale\n\nThis will install Exhale, as well as all of its dependencies.\n\nExhale Version Compatibility with Python, Sphinx, and Breathe\n----------------------------------------------------------------------------------------\n\n+----------------+----------------+----------------+-----------------+\n| Exhale Version | Python Version | Sphinx Version | Breathe Version |\n+================+================+================+=================+\n| 0.3.7          | \u003e=3.8          | \u003e=4.3.2        | \u003e=4.33.1        |\n+----------------+----------------+----------------+-----------------+\n| 0.3.2 -- 0.3.6 | \u003e=3.7          | \u003e=3.0,\u003c5       | \u003e=4.32.0        |\n+----------------+----------------+----------------+-----------------+\n| 0.3.0          | \u003e=3.6          | \u003e=3.0,\u003c5       | \u003e=4.32.0        |\n+----------------+----------------+----------------+-----------------+\n| 0.2.1 -- 0.2.4 | 2.7, 3.3+      | \u003e=1.6.1        | \"Any\"           |\n+----------------+----------------+----------------+-----------------+\n| \u003c=0.2.0        | 2.7, 3.3+      | \u003e=1.0          | \"Any\"           |\n+----------------+----------------+----------------+-----------------+\n\nFor your project's documentation requirements, adopting ``exhale@0.3.0`` means you just\nneed to specify directly that your ``docs/requirements.txt`` or similar express::\n\n    exhale\u003e=0.3.0\n\nThe ``exhale@0.3.0`` release uses the same dependencies required by ``breathe@4.32.0``.\nIf you need python 3.5 support, pin your documentation requirements to::\n\n    sphinx\u003e=2.0\n    breathe\u003e=4.13.0\n    exhale\u003c0.3.0\n\nFor Python 2.7, you should pin your documentation requirements to::\n\n    sphinx==1.8.5\n    breathe==4.12.0\n    exhale\u003c0.3.0\n\n**Order matters**, namely that ``sphinx`` and ``breathe`` appear / are installed before\n``exhale``.  Exhale 0.2.* releases support Python 2.7, but users need to be aware of the\ndependencies between Python, Sphinx, and Breathe versions.\n\n.. _credit:\n\nCredit\n----------------------------------------------------------------------------------------\n\nThis project could not exist without the already excellent tools available: Doxygen,\nSphinx, Breathe, and many others.  In particular, though, for the Tree View hierarchies\nto be successful, I vendor copies of two excellent libraries that I make no claims to.\nThey are vendored with your installation of Exhale, in accordance with each project's\nlicense:\n\n1. For non-bootstrap, I used Kate Morley's excellent and lightweight collapsibleLists_\n   including the sample CSS / images on that post.  She includes a generous\n   `CC0 1.0 license \u003chttps://iamkate.com/code/\u003e`_ for these files, as well as the rest of\n   her website.\n\n   For every HTML Theme I have tried, except for ones using bootstrap, this library\n   works reliably and consistently.  It matches the Sphinx RTD theme quite well, too!\n\n2. For bootstrap, I used Jon Miles' comprehensive `bootstrap-treeview`__ library.  Jon\n   Miles hosts this library using the\n   `Apache v2 license \u003chttps://github.com/jonmiles/bootstrap-treeview/blob/master/LICENSE\u003e`_.\n\n   This library is exceptionally well thought out and enables an impressive amount of\n   customization.  At this time, Exhale does not expose any of the available\n   customizations.  If there is a specific one you'd like to see, please join the\n   `discussion here \u003chttps://github.com/svenevs/exhale/issues/7\u003e`_.\n\nBoth of these libraries and copies of their licenses can be found in the\n`data folder of the source code \u003chttps://github.com/svenevs/exhale/tree/master/exhale/data\u003e`_.\n\n.. _collapsibleLists: https://iamkate.com/code/tree-views/\n\n__ https://github.com/jonmiles/bootstrap-treeview\n\nLicense\n----------------------------------------------------------------------------------------\n\nThis project uses a BSD 3-clause license, in hopes that it will be accessible to most\nprojects.  If you require a different license, please raise an issue and I will consider\na dual license.\n\nThe full license is\n`available here \u003chttps://github.com/svenevs/exhale/blob/master/LICENSE\u003e`_.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvenevs%2Fexhale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsvenevs%2Fexhale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsvenevs%2Fexhale/lists"}