### Multifile Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a multifile project. ```APIDOC ## Multifile ### Description Documentation for a template function in a multifile project. ### Namespace @ex_specific_multifile ### Function TestTemplateFunction (project: multifile) ``` -------------------------------- ### Typedef Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Examples showcasing the documentation of typedefs. ```APIDOC ## Typedef Examples ### Description Documentation for typedefs. ### Namespace @ex_specific_typedef ### Index (from ../../examples/specific/typedef/xml) ``` -------------------------------- ### Working doxygenconcept Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/concept.rst Use this directive to document an existing C++20 concept. Ensure Doxygen v1.9.2 or newer is installed. ```rst .. doxygenconcept:: Hashable :project: cpp_concept ``` -------------------------------- ### Image Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting an image. ```APIDOC ## Image ### Description Documentation for an image class. ### Namespace @ex_specific_image ### Class ImageClass (project: image) ``` -------------------------------- ### C Macro Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C macro. ```APIDOC ## C Macro ### Description Documentation for a C macro. ### File c_macro.h (project: c_macro) ``` -------------------------------- ### Extern Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Examples for documenting external C functions and structs. ```APIDOC ## Extern Examples ### Description Documentation for external C functions and structs. ### Namespace @ex_specific_extern_examples ### Functions - cache_tree_free (project: c_file) ### Structs - cache_tree (project: c_file, outline: true) ``` -------------------------------- ### C++ Union Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C++ union. ```APIDOC ## C++ Union ### Description Documentation for a C++ union. ### Namespace @ex_specific_cpp_union ### File cpp_union.h (project: cpp_union) ``` -------------------------------- ### C++ Macro Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C++ macro. ```APIDOC ## C++ Macro ### Description Documentation for a C++ macro. ### File define.h (project: define) ``` -------------------------------- ### Array Parameter Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example demonstrating functions with array parameters. ```APIDOC ## Array Parameter ### Description Documentation for functions accepting array parameters. ### Functions - foo (project: array) - bar (project: array) ``` -------------------------------- ### Program Listing Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a program listing. ```APIDOC ## Program Listing ### Description Documentation for a class and function within a program listing context. ### Namespace @ex_specific_program_listing ### Class Vector (project: programlisting) ### Function center (project: programlisting) ``` -------------------------------- ### C Union Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C union. ```APIDOC ## C Union ### Description Documentation for a C union. ### File c_union.h (project: c_union) ``` -------------------------------- ### All Members Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/members.rst This example shows how to document all members of a namespaced class. ```APIDOC ## All Members ### Description Documents all members of the `NamespacedClassTest` class within the `testnamespace` namespace. ### Doxygen Directives ```cpp .. cpp:namespace:: @ex_members_all .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml :members: ``` ``` -------------------------------- ### Interface Class Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting an interface class. ```APIDOC ## Interface Class ### Description Documentation for an interface class. ### Namespace @ex_specific_interface ### Interface InterfaceClass (project: interface) ``` -------------------------------- ### C++ Functions Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ functions. ```APIDOC ## C++ Functions ### Description Documentation for C++ functions. ### Namespace @ex_specific_cpp_function ### File cpp_function.h (project: cpp_function) ``` -------------------------------- ### C Typedef Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C typedef. ```APIDOC ## C Typedef ### Description Documentation for a C typedef. ### File c_typedef.h (project: c_typedef) ``` -------------------------------- ### C Struct Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C struct. ```APIDOC ## C Struct ### Description Documentation for a C struct. ### File c_struct.h (project: c_struct) ``` -------------------------------- ### C++ Enums Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ enums. ```APIDOC ## C++ Enums ### Description Documentation for C++ enums. ### Namespace @ex_specific_cpp_enum ### File cpp_enum.h (project: cpp_enum) ``` -------------------------------- ### Struct Members Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/members.rst This example demonstrates documenting members of a struct, including its constructor and a member variable. ```APIDOC ## Struct Members ### Description Documents the default constructor, copy constructor, and a member variable (`myMemberVar`) of the `MyClass` struct. ### Doxygen Directives ```cpp .. cpp:namespace:: @ex_members_struct .. doxygenfunction:: testnamespace::MyClass::MyClass() :path: ../../examples/specific/struct_function/xml .. doxygenfunction:: testnamespace::MyClass::MyClass(const MyClass&) :path: ../../examples/specific/struct_function/xml .. doxygenvariable:: testnamespace::MyClass::myMemberVar :path: ../../examples/specific/struct_function/xml ``` ``` -------------------------------- ### Install Breathe with pip Source: https://github.com/breathe-doc/breathe/blob/main/README.rst Install Breathe using pip, the Python Package Index. This is the standard method for installing Python packages. ```bash pip install breathe ``` -------------------------------- ### Function Overloads Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Examples illustrating the documentation of function overloads. ```APIDOC ## Function Overloads ### Description Documentation for various function overloads. ### Namespace @ex_specific_function_overloads ### Functions - f(int, int) (project: functionOverload) - f(double, double) (project: functionOverload) - test::g(int,int) (project: functionOverload) - test::g(double, double) (project: functionOverload) - h(std::string, MyType) (project: functionOverload) - h(std::string, MyOtherType) (project: functionOverload) - h(std::string, const int) (project: functionOverload) - h(std::string, const T, const U) (project: functionOverload) ``` -------------------------------- ### C++ Template Specialization with Namespace Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ template specialization with namespaces. ```APIDOC ## C++ Template Specialization with Namespace ### Description Documentation for C++ template specialization within a namespace. ### Namespace @ex_specific_cpp_ns_template_specialization ### File cpp_ns_template_specialization.h (project: cpp_ns_template_specialization) ``` -------------------------------- ### Namespace Outline Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/namespace.rst This example demonstrates how to display only the names of namespace members without their documentation using the 'outline' option. ```rst .. doxygennamespace:: foo :project: namespace :members: :outline: ``` -------------------------------- ### C Enum Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting a C enum. ```APIDOC ## C Enum ### Description Documentation for a C enum. ### Enum GSM_BackupFormat (project: c_enum) ``` -------------------------------- ### Template Type Alias Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Examples demonstrating the documentation of template type aliases. ```APIDOC ## Template Type Alias ### Description Documentation for template type aliases. ### Namespace @ex_specific_alias_template ### Aliases - IsFurry (from ../../examples/specific/template_type_alias/xml) - IsFuzzy (from ../../examples/specific/template_type_alias/xml) ``` -------------------------------- ### Breathe Python Extension Setup Source: https://context7.com/breathe-doc/breathe/llms.txt The `breathe.setup` function in `breathe/__init__.py` is the entry point for the Sphinx extension. It registers directives, the file-state cache, and the renderer, and is called automatically when 'breathe' is in the `extensions` list. ```python # breathe/__init__.py (simplified) from sphinx.application import Sphinx def setup(app: Sphinx): from breathe.directives.setup import setup as directive_setup from breathe.file_state_cache import setup as file_state_cache_setup from breathe.renderer.sphinxrenderer import setup as renderer_setup directive_setup(app) file_state_cache_setup(app) renderer_setup(app) return { "version": __version__, "parallel_read_safe": True, "parallel_write_safe": True, } ``` -------------------------------- ### Namespaced Function Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Examples of documenting functions within namespaces. ```APIDOC ## Namespaced Function Examples ### Description Documentation for functions within various namespaces and classes. ### Namespace @ex_specific_namespaced_function ### Functions - TestNamespaceClasses::NamespacedClassTest::function (from ../../examples/specific/class/xml) - TestNamespaceClasses::ClassTest::function (from ../../examples/specific/class/xml) - TestNamespaceClasses::ClassTest::anotherFunction (from ../../examples/specific/class/xml) - ClassTest::function (from ../../examples/specific/class/xml) - ClassTest::anotherFunction (from ../../examples/specific/class/xml) - f0 (from ../../examples/specific/class/xml) - f0< std::string > (from ../../examples/specific/class/xml) - NS1::f1 (from ../../examples/specific/class/xml) - NS1::f1< std::string > (from ../../examples/specific/class/xml) - NS1::NS2::f2 (from ../../examples/specific/class/xml) - NS1::NS2::f2< std::string > (from ../../examples/specific/class/xml) ``` -------------------------------- ### C++ Friend Classes Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ friend classes. ```APIDOC ## C++ Friend Classes ### Description Documentation for C++ friend classes. ### Namespace @ex_specific_cpp_friendclass ### File cpp_friendclass.h (project: cpp_friendclass) ``` -------------------------------- ### C++ Inherited Members Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ inherited members. ```APIDOC ## C++ Inherited Members ### Description Documentation for C++ inherited members. ### Namespace @ex_specific_cpp_inherited_members ### Classes - Base (project: cpp_inherited_members) - A (project: cpp_inherited_members) - B (project: cpp_inherited_members) ``` -------------------------------- ### No Members Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/members.rst This example shows how to document a class without explicitly listing any members. ```APIDOC ## No Members ### Description Documents the `NamespacedClassTest` class without listing any specific members, implying default member visibility or exclusion. ### Doxygen Directives ```cpp .. cpp:namespace:: @ex_members_no .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml :no-link: ``` ``` -------------------------------- ### Specific Members Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/members.rst This example demonstrates documenting only specific functions of a namespaced class. ```APIDIDOC ## Specific Members ### Description Documents only `functionS` and `anotherFunction` of the `NamespacedClassTest` class, with no links. ### Doxygen Directives ```cpp .. cpp:namespace:: @ex_members_specific .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml :members: functionS, anotherFunction :no-link: ``` ``` -------------------------------- ### Sphinx Configuration for Breathe Example Source: https://github.com/breathe-doc/breathe/blob/main/tests/data/examples/README.rst This configuration is used when running Sphinx for Breathe examples. It sets up the project name, default project, and required extensions. Ensure 'breathe' and 'sphinx.ext.graphviz' are in your extensions list. ```python project = "test" breathe_default_project = "example" breathe_show_include = False extensions = ["breathe", "sphinx.ext.graphviz"] breathe_projects = {"example": SOME_TEMPORARY_FOLDER} ``` -------------------------------- ### Run Unit Tests with make dev-test Source: https://github.com/breathe-doc/breathe/blob/main/README.rst Execute the test suite using the provided make command. This is useful for verifying the installation and functionality. ```bash make dev-test ``` -------------------------------- ### C++ Anonymous Entities Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ anonymous entities. ```APIDOC ## C++ Anonymous Entities ### Description Documentation for C++ anonymous entities. ### Namespace @ex_specific_cpp_anon ### File cpp_anon.h (project: cpp_anon) ``` -------------------------------- ### Doxygen Index XML Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/codeguide.rst An example of the index.xml file generated by Doxygen, which serves as a central reference and lists other generated files. ```xml Test member func.h ``` -------------------------------- ### Fixed Width Font Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example demonstrating the use of fixed-width font for documentation. ```APIDOC ## Fixed Width Font ### Description Documentation for a class using fixed-width font. ### Namespace @ex_specific_fixed_width ### Class Out (from ../../examples/specific/fixedwidthfont/xml, members: true) ``` -------------------------------- ### Failing Namespace Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/namespace.rst This example intentionally uses a non-existent namespace 'madeupnamespace' to demonstrate the expected warning message. ```rst .. doxygennamespace:: madeupnamespace :project: namespace ``` -------------------------------- ### C++ Code Example for Breathe Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/index.rst This is an example of C++ code that can be documented using Breathe. Ensure Doxygen is configured to generate XML output. ```cpp #include class Nutshell { public: void say_hello() { std::cout << "Hello World!\n"; } }; ``` -------------------------------- ### C++ Trailing Return Type Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Example for documenting C++ trailing return types. ```APIDOC ## C++ Trailing Return Type ### Description Documentation for C++ functions using trailing return types. ``` -------------------------------- ### Failing doxygenunion Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/union.rst This example demonstrates a failing case where the specified union does not exist. It will result in a warning message. ```rst .. doxygenunion:: made_up_union :project: union ``` -------------------------------- ### Nested List Example 1 (C++) Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/lists.rst This C++ code demonstrates the documentation structure for a nested list. ```cpp /// @brief A simple class with a nested list. /// /// This class demonstrates nested lists in Doxygen markup. /// /// Unordered list: /// + Item 1 /// + Subitem 1.1 /// + Subitem 1.2 /// + Item 2 /// /// Ordered list: /// 1. Step 1 /// 1. Substep 1.1 /// 2. Substep 1.2 /// 2. Step 2 class NestedLists_1 { public: int data; }; ``` -------------------------------- ### Failing doxygenconcept Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/concept.rst This example shows how the directive behaves when a concept is not found. A warning will be generated. ```rst .. doxygenconcept:: MadeUpConcept :project: cpp_concept ``` -------------------------------- ### Nested List Example 2 (C++) Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/lists.rst This C++ code shows documentation for another nested list structure. ```cpp /// @brief Another example of nested lists. /// /// Demonstrates mixing different list types. /// /// List 1: /// - Element A /// * Sub-element A.1 /// * Sub-element A.2 /// - Element B /// /// List 2: /// # First item /// # First sub-item /// # Second sub-item /// # Second item class NestedLists_2 { public: double value; }; ``` -------------------------------- ### Nested List Example 3 (C++) Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/lists.rst This C++ code illustrates a nested list with mixed item prefixes. ```cpp /// @brief Nested lists with mixed prefixes. /// /// Shows how different list markers can be used within nested structures. /// /// * Main item 1 /// + Sub item 1.1 /// - Sub item 1.2 /// * Main item 2 /// 1. Sub item 2.1 /// 2. Sub item 2.2 class NestedLists_3 { public: char flag; }; ``` -------------------------------- ### Nested List Example 4 (C++) Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/lists.rst This C++ code provides an example of deeply nested lists. ```cpp /// @brief Deeply nested lists. /// /// Demonstrates multiple levels of nesting. /// /// Level 1: /// + Item A /// + Level 2 Item A.1 /// - Level 3 Item A.1.1 /// - Level 3 Item A.1.2 /// + Level 2 Item A.2 /// + Item B class NestedLists_4 { public: bool status; }; ``` -------------------------------- ### Failing doxygenfile Directive Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/file.rst This example demonstrates an intentional failure case where the specified file does not exist in the Doxygen XML output. It is expected to produce a warning. ```rst .. doxygenfile:: made_up_file.h :project: nutshell ``` -------------------------------- ### C++ Function Lookup Examples Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/specific.rst Demonstrates various C++ function declarations and their Doxygen representation, including noexcept, final, override, attributes, initializers, trailing return types, and parameter packs. ```APIDOC ## C++ Function Declarations This section details various C++ function declarations and their Doxygen representation. ### `fNoexcept()` - **Description**: A function declared with noexcept. - **Signature**: `void fNoexcept()` ### `fFinal()` - **Description**: A function declared as final. - **Signature**: `void fFinal()` ### `fOverride()` - **Description**: A function declared with override. - **Signature**: `void fOverride()` ### `fAttr()` - **Description**: A function with attributes (note: Doxygen may not capture attributes in XML). - **Signature**: `void fAttr()` ### `fFInit()` - **Description**: A function with a trailing return type. - **Signature**: `auto fFInit() -> void` ### `fTrailing()` - **Description**: A function with a trailing return type. - **Signature**: `auto fTrailing() -> void` ### `fInit(int)` - **Description**: A function taking an integer parameter. - **Signature**: `void fInit(int)` ### `fPlain(int)` - **Description**: A plain function taking an integer parameter. - **Signature**: `void fPlain(int)` ### `fPtr(int*)` - **Description**: A function taking a pointer to an integer. - **Signature**: `void fPtr(int*)` ### `fLRef(int&)` - **Description**: A function taking a reference to an integer. - **Signature**: `void fLRef(int&)` ### `fRRef(int&&)` - **Description**: A function taking a rvalue reference to an integer. - **Signature**: `void fRRef(int&&)` ### `fParamPack(T...)` - **Description**: A function template taking a parameter pack. - **Signature**: `template void fParamPack(T...)` ### `fMemPtr(int A::*)` - **Description**: A function taking a pointer to a member of class A. - **Signature**: `void fMemPtr(int A::*)` ### `fParen(void (*)())` - **Description**: A function taking a pointer to a function with no arguments. - **Signature**: `void fParen(void (*)())` ### `fParenPlain(void (*)(int))` - **Description**: A function taking a pointer to a function with an integer argument. - **Signature**: `void fParenPlain(void (*)(int))` ``` -------------------------------- ### Failing Group Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/group.rst This example demonstrates an intentional failure when the specified group does not exist in the Doxygen XML output, resulting in a warning. ```rst .. doxygengroup:: madeupgroup :project: group ``` -------------------------------- ### Build Documentation with make Source: https://github.com/breathe-doc/breathe/blob/main/README.rst Build the project's documentation locally. This process involves running Doxygen and then Sphinx. ```bash make ``` -------------------------------- ### Failing doxygentypedef Example Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/typedef.rst This example demonstrates an intentional failure when the specified typedef does not exist in the Doxygen XML output. A warning will be generated. ```rst .. doxygentypedef:: made_up_typedef :project: restypedef ``` -------------------------------- ### Example C++ Struct for Doxygen Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/codeguide.rst This C++ code defines a simple struct with a comment, intended to be processed by Doxygen. It serves as an example for generating XML documentation. ```cpp /** A fluffy feline */ struct cat { /** Make this cat look super cute */ void make_cute(); }; ``` -------------------------------- ### Breathe Project Configuration Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/autoindex.rst Configure the breathe_projects_source dictionary in your conf.py to map project names to their source directories and header files. This setup is required for the autodoxygenindex directive to locate and process your C++ documentation. ```python breathe_projects_source = { "auto" : ( "../examples/specific", ["auto_function.h", "auto_class.h"] ) } ``` -------------------------------- ### Nested List Example 5 (C++) Source: https://github.com/breathe-doc/breathe/blob/main/documentation/source/lists.rst This C++ code shows a nested list using HTML tags within Doxygen. ```cpp /// @brief Nested lists using HTML. /// /// Demonstrates using HTML