From 936a0528d592b4067bf3e986b033130253cd3e2f Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 18 Mar 2020 20:42:17 +0100 Subject: [PATCH 01/11] Update MockStateMachine --- tests/test_renderer.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/tests/test_renderer.py b/tests/test_renderer.py index d828f1f0..fc466053 100644 --- a/tests/test_renderer.py +++ b/tests/test_renderer.py @@ -110,6 +110,9 @@ class MockStateMachine: def __init__(self): self.reporter = MockReporter() + def get_source_and_line(self, lineno: int): + return 'mock-doc', lineno + class MockMaskFactory: def __init__(self): From a1d3b089eae14e0a64b8eaf67bc79ea6d9a9ce25 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 18 Mar 2020 21:03:22 +0100 Subject: [PATCH 02/11] Bump to Sphinx >= 3 --- .github/workflows/unit_tests.yml | 23 +++++------------------ .travis.yml | 2 +- requirements/production.txt | 2 +- setup.py | 2 +- 4 files changed, 8 insertions(+), 21 deletions(-) diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index 7eff6eaa..85c500d5 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -6,25 +6,12 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: [3.5, 3.6, 3.7, 3.8] + python-version: [3.6, 3.7, 3.8] sphinx-version: - - 2.0.0 - - 2.0.1 - - 2.1.0 - - 2.1.1 - - 2.1.2 - - 2.2.0 - - 2.2.1 - - 2.2.2 - - 2.3.0 - - 2.4.0 - - 2.4.1 - - 2.4.2 - - 2.4.3 - - 2.4.4 - - git+https://github.com/sphinx-doc/sphinx.git@2.x - #- git+https://github.com/sphinx-doc/sphinx.git@3.x - #- git+https://github.com/sphinx-doc/sphinx.git@master + - 3.0.0 + - git+https://github.com/sphinx-doc/sphinx.git@3.0.x + - git+https://github.com/sphinx-doc/sphinx.git@3.x + - git+https://github.com/sphinx-doc/sphinx.git@master steps: - uses: actions/checkout@v2 diff --git a/.travis.yml b/.travis.yml index a7c29ea5..d90bfff9 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,7 @@ language: python env: - - SPHINX_VERSION=2.4.4 TRAVIS_CI=True + - SPHINX_VERSION=3.0 TRAVIS_CI=True python: - "3.5" diff --git a/requirements/production.txt b/requirements/production.txt index 92502992..5541eedf 100644 --- a/requirements/production.txt +++ b/requirements/production.txt @@ -2,5 +2,5 @@ docutils>=0.12 Jinja2>=2.7.3 MarkupSafe>=0.23 Pygments>=1.6 -Sphinx>=2.0 +Sphinx>=3.0 six>=1.9.0 diff --git a/setup.py b/setup.py index db3be627..ca4bd77d 100644 --- a/setup.py +++ b/setup.py @@ -15,7 +15,7 @@ render `Doxygen `__ xml output. ''' -requires = ['Sphinx>=2.0', 'docutils>=0.12', 'six>=1.9'] +requires = ['Sphinx>=3.0', 'docutils>=0.12', 'six>=1.9'] if sys.version_info < (3, 5): print('ERROR: Sphinx requires at least Python 3.5 to run.') From 802b53ac508dd68c059a5cae10bba2556135badf Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 18 Mar 2020 20:56:05 +0100 Subject: [PATCH 03/11] Update use of cpp.DefinitionParser --- breathe/renderer/sphinxrenderer.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py index 9dd67f55..cb8c9322 100644 --- a/breathe/renderer/sphinxrenderer.py +++ b/breathe/renderer/sphinxrenderer.py @@ -53,11 +53,9 @@ def parse_definition(self, parser): # build a name object # TODO: work out if we can use base.refid in a pending_xref somewhere - try: - parser = cpp.DefinitionParser(namestr, self, self.env.config) - except TypeError: - # sphinx < 1.5 - parser = cpp.DefinitionParser(namestr, self) + parser = cpp.DefinitionParser(namestr, + location=self.get_source_info(), + config=self.env.config) name = parser._parse_nested_name() parser.assert_end() From cee5cd1e068d7ce16b7ed0ffd55c46fa5468b609 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 18 Mar 2020 20:56:41 +0100 Subject: [PATCH 04/11] Update use of the C domain --- breathe/renderer/sphinxrenderer.py | 20 +++++++++++++++++--- tests/test_renderer.py | 2 +- 2 files changed, 18 insertions(+), 4 deletions(-) diff --git a/breathe/renderer/sphinxrenderer.py b/breathe/renderer/sphinxrenderer.py index cb8c9322..d5654e15 100644 --- a/breathe/renderer/sphinxrenderer.py +++ b/breathe/renderer/sphinxrenderer.py @@ -87,7 +87,17 @@ class DomainDirectiveFactory(object): 'union': (cpp.CPPUnionObject, 'union'), 'namespace': (cpp.CPPTypeObject, 'type'), 'enumvalue': (cpp.CPPEnumeratorObject, 'enumerator'), - 'define': (c.CObject, 'macro') + 'define': (c.CMacroObject, 'macro'), + } + c_classes = { + 'variable': (c.CMemberObject, 'var'), + 'function': (c.CFunctionObject, 'function'), + 'define': (c.CMacroObject, 'macro'), + 'struct': (c.CStructObject, 'struct'), + 'union': (c.CUnionObject, 'union'), + 'enum': (c.CEnumObject, 'enum'), + 'enumvalue': (c.CEnumeratorObject, 'enumerator'), + 'typedef': (c.CTypeObject, 'type'), } python_classes = { @@ -115,8 +125,12 @@ def fix_python_signature(sig): @staticmethod def create(domain, args): if domain == 'c': - return c.CObject(*args) - if domain == 'py': + if args[0] not in DomainDirectiveFactory.c_classes: + print("Unknown C directive:", args[0]) + print("args:", args) + cls, name = DomainDirectiveFactory.c_classes[args[0]] + args[1] = [n.replace('::', '.') for n in args[1]] + elif domain == 'py': cls, name = DomainDirectiveFactory.python_classes.get( args[0], (python.PyClasslike, 'class')) args[1] = [DomainDirectiveFactory.fix_python_signature(n) for n in args[1]] diff --git a/tests/test_renderer.py b/tests/test_renderer.py index fc466053..4c9133ab 100644 --- a/tests/test_renderer.py +++ b/tests/test_renderer.py @@ -283,7 +283,7 @@ def test_render_c_typedef(app): def test_render_c_function_typedef(app): member_def = WrappedMemberDef(kind='typedef', definition='typedef void* (*voidFuncPtr)(float, int)') signature = find_node(render(app, member_def, domain='c'), 'desc_signature') - assert signature.astext().startswith('typedef void*') + assert signature.astext().startswith('typedef void *') params = find_node(signature, 'desc_parameterlist') assert len(params) == 2 assert params[0].astext() == "float" From aedbc98dd5f860574158b67953be8d145f2ac4b7 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 25 Mar 2020 19:26:45 +0100 Subject: [PATCH 05/11] Update conf.py to Python 3 --- documentation/source/conf.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/source/conf.py b/documentation/source/conf.py index 5963fc9c..d76146a7 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -37,8 +37,8 @@ # Get a description of the current position. Use Popen for 2.6 compat git_tag = subprocess.Popen(['git', 'describe', '--tags'], stdout=subprocess.PIPE).communicate()[0] -# Convert to unicode for python3 -git_tag = unicode(git_tag) +# convert from bytes to string +git_tag = git_tag.decode('ascii') if travis_build: @@ -317,8 +317,8 @@ # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ - ('index', 'BreatheExample.tex', ur'BreatheExample Documentation', - ur'Michael Jones', 'manual'), + ('index', 'BreatheExample.tex', 'BreatheExample Documentation', + 'Michael Jones', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of From 9a651b8af3e47ca16c16a9eb0120ea948e844584 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 27 Mar 2020 11:13:17 +0100 Subject: [PATCH 06/11] conf.py, fix domain_by_file_pattern The patterns are matched against filenames, not paths. --- documentation/source/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/source/conf.py b/documentation/source/conf.py index d76146a7..65115d21 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -226,9 +226,9 @@ } breathe_domain_by_file_pattern = { - "*/class.h" : "cpp", - "*/alias.h" : "c", - "*/c_enum.h" : "c", + "class.h" : "cpp", + "alias.h" : "c", + "c_enum.h" : "c", "c_typedef.h" : "c", } From cc417ceb912948d8f97379acd43da92bf9a0fdf6 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Wed, 25 Mar 2020 22:05:19 +0100 Subject: [PATCH 07/11] Update docs to prevent most duplicate delcarations. Use .. cpp:namespace:: to put each example in its own namespace. --- documentation/Makefile | 2 +- documentation/source/autofile.rst | 1 - documentation/source/autoindex.rst | 3 +- documentation/source/class.rst | 30 +++++++---- documentation/source/domains.rst | 10 ++++ documentation/source/doxygen.rst | 80 ++++++++++++++++++++++++++++ documentation/source/embeddedrst.rst | 3 +- documentation/source/enum.rst | 8 ++- documentation/source/enumvalue.rst | 8 ++- documentation/source/file.rst | 9 +++- documentation/source/function.rst | 8 ++- documentation/source/group.rst | 23 +++++--- documentation/source/groups.rst | 2 + documentation/source/index.rst | 2 + documentation/source/inline.rst | 2 +- documentation/source/latexmath.rst | 3 +- documentation/source/lists.rst | 22 ++++++++ documentation/source/markups.rst | 12 +++-- documentation/source/members.rst | 14 ++--- documentation/source/namespace.rst | 26 ++++++--- documentation/source/specific.rst | 55 ++++++++----------- documentation/source/struct.rst | 23 +++++--- documentation/source/template.rst | 8 +++ documentation/source/tinyxml.rst | 2 + documentation/source/typedef.rst | 8 ++- documentation/source/union.rst | 8 ++- documentation/source/variable.rst | 4 ++ 27 files changed, 285 insertions(+), 91 deletions(-) diff --git a/documentation/Makefile b/documentation/Makefile index 03d6c8f1..c5f1fe9b 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = +SPHINXOPTS = -vn SPHINXBUILD = sphinx-build PAPER = BUILDDIR ?= build diff --git a/documentation/source/autofile.rst b/documentation/source/autofile.rst index a908e384..ad30d554 100644 --- a/documentation/source/autofile.rst +++ b/documentation/source/autofile.rst @@ -22,4 +22,3 @@ It produces this output: .. autodoxygenfile:: auto_class.h :project: auto - :no-link: diff --git a/documentation/source/autoindex.rst b/documentation/source/autoindex.rst index 9b87c89c..fa12c293 100644 --- a/documentation/source/autoindex.rst +++ b/documentation/source/autoindex.rst @@ -20,7 +20,8 @@ With the following config value:: It produces this output: +.. cpp:namespace:: @ex_autoindex + .. autodoxygenindex:: :project: auto - :no-link: diff --git a/documentation/source/class.rst b/documentation/source/class.rst index 8c5f28e2..7a5a6edd 100644 --- a/documentation/source/class.rst +++ b/documentation/source/class.rst @@ -43,6 +43,8 @@ specified class. Basic Example ------------- +.. cpp:namespace:: @ex_class_basic + This displays the class documentation without any members: .. code-block:: rst @@ -54,12 +56,13 @@ It produces this output: .. doxygenclass:: Nutshell :project: nutshell - :no-link: Template Specialisation Example ------------------------------- +.. cpp:namespace:: @ex_class_template_spec + You can reference class template specialisations by include the specialisation in the name: @@ -72,7 +75,6 @@ Produces this output: .. doxygenclass:: TemplateClass< T * > :project: template_specialisation - :no-link: Where as without the specialisation, the directive references the generic declaration: @@ -86,12 +88,13 @@ Produces this output: .. doxygenclass:: TemplateClass :project: template_specialisation - :no-link: Members Example --------------- +.. cpp:namespace:: @ex_class_members + This directive call will display the class documentation with all the public members: @@ -106,12 +109,13 @@ It produces this output: .. doxygenclass:: Nutshell :project: nutshell :members: - :no-link: Specific Members Example ------------------------ +.. cpp:namespace:: @ex_class_members_specific + This displays the class documentation with only the members listed in the ``:members:`` option: @@ -126,12 +130,13 @@ It produces this output: .. doxygenclass:: Nutshell :project: nutshell :members: crack, isCracked - :no-link: Protected Members ----------------- +.. cpp:namespace:: @ex_class_members_protected + This displays only the protected members of the class. Normally this is combined with the ``:members:`` option to show the public members as well. @@ -146,12 +151,13 @@ It produces this output: .. doxygenclass:: GroupedClassTest :project: group :protected-members: - :no-link: Private Members --------------- +.. cpp:namespace:: @ex_class_members_private + This displays only the private members of the class. Normally this is combined with the ``:members:`` option to show the public members as well. @@ -166,11 +172,12 @@ It produces this output: .. doxygenclass:: Nutshell :project: nutshell :private-members: - :no-link: Undocumented Members -------------------- +.. cpp:namespace:: @ex_class_members_undocumented + This displays the undocumented members of the class which are suppressed by default. Undocumented public members are only shown if the ``:members:`` option is also used. The same goes for the undocumented private members and the @@ -191,7 +198,6 @@ It produces this output: :members: :private-members: :undoc-members: - :no-link: .. note:: @@ -201,6 +207,8 @@ It produces this output: Outline Example --------------- +.. cpp:namespace:: @ex_class_outline + This displays only the names of the class members and not their documentation. The ``:members:`` and ``:private-members:`` options determine which members are displayed. @@ -218,12 +226,13 @@ It produces this output: :project: nutshell :members: :outline: - :no-link: Qt Signals & Slots Example -------------------------- +.. cpp:namespace:: @ex_class_qt + Doxygen is aware of Qt Signals and Slots and so Breathe can pick them up and display them in the output. They are displayed in appropriate ``Signals``, ``Public Slots``, ``Protected Slots`` and ``Private Slots`` sections. @@ -239,11 +248,12 @@ Produces the following output: .. doxygenclass:: QtSignalSlotExample :project: qtsignalsandslots :members: - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_class_failing + This intentionally fails: .. code-block:: rst diff --git a/documentation/source/domains.rst b/documentation/source/domains.rst index 70ef66f2..cd0452aa 100644 --- a/documentation/source/domains.rst +++ b/documentation/source/domains.rst @@ -15,6 +15,8 @@ The following targets are supported: Class Example ------------- +.. cpp:namespace:: @ex_domains_class + Given the following Breathe directives:: .. doxygenclass:: testnamespace::NamespacedClassTest @@ -38,6 +40,8 @@ which renders as: :cpp:class:`another reference `. Note the use of the Typedef Examples ---------------- +.. cpp:namespace:: @ex_domains_typedef + Given the following Breathe directives:: .. doxygentypedef:: TestTypedef @@ -140,6 +148,8 @@ which renders as :cpp:type:`TestClass::MemberTypedef`. Enum Value Examples ------------------- +.. cpp:namespace:: @ex_domains_enum + Given the following Breathe directives:: .. doxygenenumvalue:: VALUE diff --git a/documentation/source/doxygen.rst b/documentation/source/doxygen.rst index 128437ca..bd11a7db 100644 --- a/documentation/source/doxygen.rst +++ b/documentation/source/doxygen.rst @@ -5,142 +5,222 @@ Doxygen Test Suite Class ----- +.. cpp:namespace:: @ex_doxygen_class + .. doxygenindex:: :project: class Interface --------- + +.. cpp:namespace:: @ex_doxygen_interface + .. doxygenindex:: :path: ../../examples/doxygen/interface/xml Define ------ +.. the macros are in the C domain, and anyway in global scope +.. cpp:namespace:: 0 + .. doxygenindex:: :path: ../../examples/doxygen/define/xml Enum ---- + +.. cpp:namespace:: @ex_doxygen_enum + .. doxygenindex:: :path: ../../examples/doxygen/enum/xml File ----- + +.. cpp:namespace:: @ex_doxygen_file + .. doxygenindex:: :path: ../../examples/doxygen/file/xml Func ---- + +.. cpp:namespace:: @ex_doxygen_func + .. doxygenindex:: :path: ../../examples/doxygen/func/xml Page ---- + +.. this is not related to Sphinx, but let's reset the namespace anyway +.. cpp:namespace:: 0 + .. doxygenindex:: :path: ../../examples/doxygen/page/xml Relates ------- + +.. cpp:namespace:: @ex_doxygen_relates + .. doxygenindex:: :path: ../../examples/doxygen/relates/xml Author ------ + +.. cpp:namespace:: @ex_doxygen_author + .. doxygenindex:: :path: ../../examples/doxygen/author/xml Par --- + +.. cpp:namespace:: @ex_doxygen_par + .. doxygenindex:: :path: ../../examples/doxygen/par/xml Overload -------- + +.. cpp:namespace:: @ex_doxygen_overload + .. doxygenindex:: :path: ../../examples/doxygen/overload/xml Example ------- + +.. cpp:namespace:: @ex_doxygen_example + .. doxygenindex:: :path: ../../examples/doxygen/example/xml Include ------- + +.. cpp:namespace:: @ex_doxygen_include + .. doxygenindex:: :path: ../../examples/doxygen/include/xml QtStyle ------- + +.. cpp:namespace:: @ex_doxygen_qtstyle + .. doxygenindex:: :path: ../../examples/doxygen/qtstyle/xml JdStyle ------- + +.. cpp:namespace:: @ex_doxygen_jdstyle + .. doxygenindex:: :path: ../../examples/doxygen/jdstyle/xml StructCmd --------- + +.. cpp:namespace:: @ex_doxygen_structcmd + .. doxygenindex:: :path: ../../examples/doxygen/structcmd/xml Autolink -------- + +.. cpp:namespace:: @ex_doxygen_autolink + .. doxygenindex:: :path: ../../examples/doxygen/autolink/xml ResTypeDef ---------- + +.. cpp:namespace:: @ex_doxygen_restypedef + .. doxygenindex:: :path: ../../examples/doxygen/restypedef/xml AfterDoc -------- + +.. cpp:namespace:: @ex_doxygen_afterdoc + .. doxygenindex:: :path: ../../examples/doxygen/afterdoc/xml Template -------- + +.. cpp:namespace:: @ex_doxygen_template + .. doxygenindex:: :path: ../../examples/doxygen/template/xml Tag --- + +.. cpp:namespace:: @ex_doxygen_tag + .. doxygenindex:: :path: ../../examples/doxygen/tag/xml Group ----- + +.. cpp:namespace:: @ex_doxygen_group + .. doxygenindex:: :path: ../../examples/doxygen/group/xml Diagrams -------- + +.. cpp:namespace:: @ex_doxygen_diagrams + .. doxygenindex:: :path: ../../examples/doxygen/diagrams/xml Memgrp ------ + +.. cpp:namespace:: @ex_doxygen_memgrp + .. doxygenindex:: :path: ../../examples/doxygen/memgrp/xml Docstring --------- + .. doxygenindex:: :path: ../../examples/doxygen/docstring/xml PyExample --------- + .. doxygenindex:: :path: ../../examples/doxygen/pyexample/xml Mux --- + +.. cpp:namespace:: @ex_doxygen_mux + .. doxygenindex:: :path: ../../examples/doxygen/mux/xml Manual ------ + +.. cpp:namespace:: @ex_doxygen_manual + .. doxygenindex:: :path: ../../examples/doxygen/manual/xml diff --git a/documentation/source/embeddedrst.rst b/documentation/source/embeddedrst.rst index c8598261..673a7aaa 100644 --- a/documentation/source/embeddedrst.rst +++ b/documentation/source/embeddedrst.rst @@ -2,7 +2,8 @@ Embedded ReStructuredText ========================= +.. cpp:namespace:: @ex_embedded_rst + .. doxygenindex:: :path: ../../examples/specific/rst/xml - :no-link: diff --git a/documentation/source/enum.rst b/documentation/source/enum.rst index f83d968a..43d1ce8a 100644 --- a/documentation/source/enum.rst +++ b/documentation/source/enum.rst @@ -7,6 +7,8 @@ doxygenenum Directive Example Working Example --------------- +.. cpp:namespace:: @ex_enum_example + This should work:: .. doxygenenum:: NodeType @@ -16,11 +18,12 @@ It produces this output: .. doxygenenum:: NodeType :project: tinyxml - :no-link: Example with Namespace ---------------------- +.. cpp:namespace:: @ex_enum_namespace + This should work:: .. doxygenenum:: foo::ns::Letters @@ -30,11 +33,12 @@ It produces this output: .. doxygenenum:: foo::ns::Letters :project: namespace - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_enum_failing + This intentionally fails:: .. doxygenenum:: made_up_enum diff --git a/documentation/source/enumvalue.rst b/documentation/source/enumvalue.rst index 990f2a18..ae05cf0d 100644 --- a/documentation/source/enumvalue.rst +++ b/documentation/source/enumvalue.rst @@ -7,6 +7,8 @@ doxygenenumvalue Directive Example Working Example --------------- +.. cpp:namespace:: @ex_enumvalue_example + This should work:: .. doxygenenumvalue:: TIXML_NO_ERROR @@ -16,11 +18,12 @@ It produces this output: .. doxygenenumvalue:: TIXML_NO_ERROR :project: tinyxml - :no-link: Example with Namespace ---------------------- +.. cpp:namespace:: @ex_enumvalue_namespace + This should work:: .. doxygenenumvalue:: foo::ns::A @@ -30,11 +33,12 @@ It produces this output: .. doxygenenumvalue:: foo::ns::A :project: namespace - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_enumvalue_failing + This intentionally fails:: .. doxygenenumvalue:: made_up_enumvalue diff --git a/documentation/source/file.rst b/documentation/source/file.rst index 5a0b764f..f3fa95f8 100644 --- a/documentation/source/file.rst +++ b/documentation/source/file.rst @@ -7,6 +7,8 @@ doxygenfile Directive Example Example ------- +.. cpp:namespace:: @ex_file_example + This should work:: .. doxygenfile:: nutshell.h @@ -18,11 +20,12 @@ It produces this output: .. doxygenfile:: nutshell.h :project: nutshell - :no-link: Example with Nested Namespaces ------------------------------ +.. cpp:namespace:: @ex_file_namespace + This should work:: .. doxygenfile:: namespacefile.h @@ -39,6 +42,8 @@ It produces this output: Example for Multiple Files -------------------------- +.. cpp:namespace:: @ex_file_multiple_files + When there are multiple files with the same name in the project, you need to be more specific with the filename you provide. For example, in a project with the following two files:: @@ -57,6 +62,8 @@ To uniquely identify them. Failing Example --------------- +.. cpp:namespace:: @ex_file_failing + This intentionally fails:: .. doxygenfile:: made_up_file.h diff --git a/documentation/source/function.rst b/documentation/source/function.rst index f768b3f1..244208e4 100644 --- a/documentation/source/function.rst +++ b/documentation/source/function.rst @@ -18,6 +18,8 @@ extensions listed in the :ref:`breathe_implementation_filename_extensions Working Example --------------- +.. cpp:namespace:: @ex_function_example + This should work:: .. doxygenfunction:: open @@ -27,11 +29,12 @@ It produces this output: .. doxygenfunction:: open :project: structcmd - :no-link: Separated Declaration & Implementation Example ---------------------------------------------- +.. cpp:namespace:: @ex_function_separated + This should work:: .. doxygenfunction:: open_di @@ -41,11 +44,12 @@ It produces this output: .. doxygenfunction:: open_di :project: decl_impl - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_function_failing + This intentionally fails:: .. doxygenfunction:: made_up_function diff --git a/documentation/source/group.rst b/documentation/source/group.rst index 696b1a96..68707bd4 100644 --- a/documentation/source/group.rst +++ b/documentation/source/group.rst @@ -50,6 +50,8 @@ variable to set it in the ``conf.py``. Basic Example ------------- +.. cpp:namespace:: @ex_group_basic + The plain ``doxygengroup`` directive will output the group name and description and any top level publicly visible members of the group. @@ -62,11 +64,12 @@ It produces this output: .. doxygengroup:: mygroup :project: group - :no-link: Content-Only Example -------------------- +.. cpp:namespace:: @ex_group_content_only + The ``content-only`` option changes the output to only include the content of the group and not the group name or description. So this: @@ -81,7 +84,6 @@ Produces this output: .. doxygengroup:: mygroup :project: group :content-only: - :no-link: .. note:: @@ -93,6 +95,8 @@ Produces this output: Members Example --------------- +.. cpp:namespace:: @ex_group_members + The ``members`` option changes the output to include the public members of any classes. The output for any class in the group should be the same as if it had be produced by the :ref:`doxygenclass directive ` with the @@ -109,12 +113,13 @@ It produces this output: .. doxygengroup:: mygroup :project: group :members: - :no-link: Protected Members Example ------------------------- +.. cpp:namespace:: @ex_group_members_protected + The ``protected-members`` option changes the output to include the protected members of any classes. The output for any class in the group should be the same as if it had be produced by the :ref:`doxygenclass directive ` @@ -131,12 +136,13 @@ It produces this output: .. doxygengroup:: mygroup :project: group :protected-members: - :no-link: Private-Members Example ----------------------- +.. cpp:namespace:: @ex_group_members_private + The ``private-members`` option changes the output to include the private members of any classes. The output for any class in the group should be the same as if it had be produced by the :ref:`doxygenclass directive ` with the @@ -153,12 +159,13 @@ Produces this output: .. doxygengroup:: mygroup :project: group :private-members: - :no-link: Undocumented Members Example ---------------------------- +.. cpp:namespace:: @ex_group_members_undocumented + The ``undoc-members`` option changes the output to include any undocumentated members from the sections (public, protected, private) that are being displayed for the classes in the group output. @@ -176,7 +183,6 @@ Produces this output: :project: group :private-members: :undoc-members: - :no-link: .. note:: @@ -187,6 +193,8 @@ Produces this output: Outline Example --------------- +.. cpp:namespace:: @ex_group_outline + This displays only the names of the members of the group and not their documentation. The other options determine which members are displayed. @@ -203,12 +211,13 @@ It produces this output: :project: group :members: :outline: - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_group_failing + This intentionally fails: .. code-block:: rst diff --git a/documentation/source/groups.rst b/documentation/source/groups.rst index 70657085..2c172dfa 100644 --- a/documentation/source/groups.rst +++ b/documentation/source/groups.rst @@ -2,6 +2,8 @@ Groups ====== +.. cpp:namespace:: @ex_groups + Breathe has basic support for the grouping functionality that Doxygen provides. Using the example from the Doxygen docs: diff --git a/documentation/source/index.rst b/documentation/source/index.rst index fcba65a4..4535cf50 100644 --- a/documentation/source/index.rst +++ b/documentation/source/index.rst @@ -139,6 +139,8 @@ You get something like this: ---- +.. cpp:namespace:: @ex_index + .. doxygenclass:: Nutshell :project: nutshell :members: diff --git a/documentation/source/inline.rst b/documentation/source/inline.rst index 6bbe6110..fe58778a 100644 --- a/documentation/source/inline.rst +++ b/documentation/source/inline.rst @@ -13,9 +13,9 @@ description text ends have failed. Something for future work. Example ------- +.. cpp:namespace:: @ex_inline .. doxygenindex:: :path: ../../examples/specific/inline/xml - :no-link: diff --git a/documentation/source/latexmath.rst b/documentation/source/latexmath.rst index 999c9c68..3f65211c 100644 --- a/documentation/source/latexmath.rst +++ b/documentation/source/latexmath.rst @@ -25,11 +25,12 @@ class with a comment like:: Will be renderer as: +.. cpp:namespace:: @ex_latexmath + .. doxygenclass:: MathHelper :project: latexmath :members: :undoc-members: - :no-link: Without any additional configuration except for including a math extension in diff --git a/documentation/source/lists.rst b/documentation/source/lists.rst index 1109c61e..bc9fcb52 100644 --- a/documentation/source/lists.rst +++ b/documentation/source/lists.rst @@ -4,6 +4,8 @@ Lists Breathe has support for lists in the doxygen documentation. They are output as follows. +.. cpp:namespace:: @ex_lists_plus + For unordered lists with list items prefixed with **+** :: .. doxygenclass:: SimpleList_1 @@ -18,6 +20,8 @@ It renders as: ---- +.. cpp:namespace:: @ex_lists_dash + Unordered lists with list items prefixed with **-** render as: ---- @@ -27,6 +31,8 @@ Unordered lists with list items prefixed with **-** render as: ---- +.. cpp:namespace:: @ex_lists_star + Unordered lists with list items prefixed with **\*** render as: ---- @@ -36,6 +42,8 @@ Unordered lists with list items prefixed with **\*** render as: ---- +.. cpp:namespace:: @ex_lists_html + Unordered lists defined using HTML tags **
  • ** render as: ---- @@ -45,6 +53,8 @@ Unordered lists defined using HTML tags **
    • ** render as: ---- +.. cpp:namespace:: @ex_lists_auto + Auto-numbered lists with list items prefixed with **-#** render as: ---- @@ -54,6 +64,8 @@ Auto-numbered lists with list items prefixed with **-#** render as: ---- +.. cpp:namespace:: @ex_lists_arabic + Numbered lists with list items prefixed with Arabic numerals **1. 2. ...** render as: ---- @@ -70,6 +82,8 @@ Nested lists are supported in all combinations, as long as they are valid doxyge Below are a couple of examples of different nested lists documentation and their corresponding breathe output. +.. cpp:namespace:: @ex_lists_nested_1 + Documentation looking like this: .. literalinclude:: code/nested_list_1.h @@ -84,6 +98,8 @@ renders as: ---- +.. cpp:namespace:: @ex_lists_nested_2 + Documentation looking like this: .. literalinclude:: code/nested_list_2.h @@ -98,6 +114,8 @@ renders as: ---- +.. cpp:namespace:: @ex_lists_nested_3 + Documentation looking like this: .. literalinclude:: code/nested_list_3.h @@ -112,6 +130,8 @@ renders as: ---- +.. cpp:namespace:: @ex_lists_nested_4 + Documentation looking like this: .. literalinclude:: code/nested_list_4.h @@ -126,6 +146,8 @@ renders as: ---- +.. cpp:namespace:: @ex_lists_nested_5 + Documentation looking like this: .. literalinclude:: code/nested_list_5.h diff --git a/documentation/source/markups.rst b/documentation/source/markups.rst index 3010477e..a76c7a6d 100644 --- a/documentation/source/markups.rst +++ b/documentation/source/markups.rst @@ -13,6 +13,8 @@ within appropriately demarcated sections. reStructuredText ---------------- +.. cpp:namespace:: @ex_markups_rst + Breathe supports reStructuredText within doxygen **verbatim** blocks which begin with the markup **embed:rst**. This means that a comment block like this:: @@ -29,11 +31,12 @@ Will be rendered as: .. doxygenfunction:: TestClass::rawVerbatim :project: rst - :no-link: Handling Leading Asterisks ~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. cpp:namespace:: @ex_markups_leading_star + Note that doxygen captures **all** content in a **verbatim** block. This can be rather an annoyance if you use a leading-asterisk style of comment block such as the following:: @@ -86,13 +89,14 @@ This will appropriately handle the leading asterisks and render as: .. doxygenfunction:: TestClass::rawLeadingAsteriskVerbatim :project: rst - :no-link: ---- Handling Leading Slashes ~~~~~~~~~~~~~~~~~~~~~~~~ +.. cpp:namespace:: @ex_markups_leading_slash + Similar troubles can be encountered when using comment blocks that start with a triple forward slash. For example:: @@ -120,13 +124,14 @@ This will appropriately handle the leading slashes and render as: .. doxygenfunction:: TestClass::rawLeadingSlashesVerbatim :project: rst - :no-link: ---- Aliases ~~~~~~~ +.. cpp:namespace:: @ex_markups_aliases + To make these blocks appears as more appropriate doxygen-like markup in your comments you can add the following aliases to your doxygen configuration file:: @@ -165,6 +170,5 @@ Which will be rendered as: .. doxygenfunction:: TestClass::function :project: rst - :no-link: diff --git a/documentation/source/members.rst b/documentation/source/members.rst index 9640a9fd..805bcb8d 100644 --- a/documentation/source/members.rst +++ b/documentation/source/members.rst @@ -5,34 +5,36 @@ Members Tests All Members ----------- +.. cpp:namespace:: @ex_members_all + .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml :members: - :no-link: - Specific Members ---------------- +.. cpp:namespace:: @ex_members_specific + .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml :members: functionS, anotherFunction - :no-link: No Members ---------- +.. cpp:namespace:: @ex_members_no + .. doxygenclass:: testnamespace::NamespacedClassTest :path: ../../examples/specific/members/xml - :no-link: Struct Members ---------------- +.. cpp:namespace:: @ex_members_struct + .. doxygenfunction:: testnamespace::MyClass::MyClass :path: ../../examples/specific/struct_function/xml - :no-link: .. doxygenfunction:: testnamespace::MyClass::MyClass(const MyClass&) :path: ../../examples/specific/struct_function/xml - :no-link: diff --git a/documentation/source/namespace.rst b/documentation/source/namespace.rst index 70567d5e..2aaf420d 100644 --- a/documentation/source/namespace.rst +++ b/documentation/source/namespace.rst @@ -47,6 +47,8 @@ variable to set it in the ``conf.py``. Basic Example ------------- +.. cpp:namespace:: @ex_namespace_basic + The plain ``doxygennamespace`` directive will output the namespace name and description and any top level publicly visible members of the namespace. @@ -59,11 +61,12 @@ It produces this output: .. doxygennamespace:: foo :project: namespace - :no-link: Content-Only Example -------------------- +.. cpp:namespace:: @ex_namespace_content_only + The ``content-only`` option changes the output to only include the content of the namespace and not the namespace name or description. So this: @@ -78,7 +81,6 @@ Produces this output: .. doxygennamespace:: foo :project: namespace :content-only: - :no-link: .. note:: @@ -90,6 +92,8 @@ Produces this output: Members Example --------------- +.. cpp:namespace:: @ex_namespace_members + The ``members`` option changes the output to include the public members of any classes. The output for any class in the namespace should be the same as if it had be produced by the :ref:`doxygenclass directive ` with the @@ -106,12 +110,13 @@ It produces this output: .. doxygennamespace:: foo :project: namespace :members: - :no-link: Protected Members Example ------------------------- +.. cpp:namespace:: @ex_namespace_members_protected + The ``protected-members`` option changes the output to include the protected members of any classes. The output for any class in the namespace should be the same as if it had be produced by the :ref:`doxygenclass directive ` @@ -128,12 +133,13 @@ It produces this output: .. doxygennamespace:: foo :project: namespace :protected-members: - :no-link: Private-Members Example ----------------------- +.. cpp:namespace:: @ex_namespace_members_private + The ``private-members`` option changes the output to include the private members of any classes. The output for any class in the namespace should be the same as if it had be produced by the :ref:`doxygenclass directive ` with the @@ -150,12 +156,13 @@ Produces this output: .. doxygennamespace:: foo :project: namespace :private-members: - :no-link: Undocumented Members Example ---------------------------- +.. cpp:namespace:: @ex_namespace_members_undocumented + The ``undoc-members`` option changes the output to include any undocumentated members from the sections (public, protected, private) that are being displayed for the classes in the namespace output. @@ -173,7 +180,6 @@ Produces this output: :project: namespace :private-members: :undoc-members: - :no-link: .. note:: @@ -185,6 +191,8 @@ Produces this output: Outline Example --------------- +.. cpp:namespace:: @ex_namespace_outline + This displays only the names of the members of the namespace and not their documentation. The other options determine which members are displayed. @@ -201,12 +209,13 @@ It produces this output: :project: namespace :members: :outline: - :no-link: Nested Example -------------- +.. cpp:namespace:: @ex_namespace_nested + The referenced namespace can be nested in another namespace. .. code-block:: rst @@ -218,12 +227,13 @@ Produces this output: .. doxygennamespace:: foo::ns :project: namespace - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_namespace_failing + This intentionally fails: .. code-block:: rst diff --git a/documentation/source/specific.rst b/documentation/source/specific.rst index 8bdc967d..3acc0f2d 100644 --- a/documentation/source/specific.rst +++ b/documentation/source/specific.rst @@ -6,158 +6,149 @@ Specific Examples Test Suite Template Type Alias ------------------- +.. cpp:namespace:: @ex_specific_alias_template + .. doxygentypedef:: IsFurry :path: ../../examples/specific/template_type_alias/xml - :no-link: .. doxygentypedef:: IsFuzzy :path: ../../examples/specific/template_type_alias/xml - :no-link: Typedef Examples ---------------- +.. cpp:namespace:: @ex_specific_typedef + .. doxygenindex:: :path: ../../examples/specific/typedef/xml - :no-link: - Namespaced Function Examples ---------------------------- +.. cpp:namespace:: @ex_specific_namespaced_function + .. doxygenfunction:: testnamespace::NamespacedClassTest::function :path: ../../examples/specific/class/xml - :no-link: .. doxygenfunction:: testnamespace::ClassTest::function :path: ../../examples/specific/class/xml - :no-link: .. doxygenfunction:: testnamespace::ClassTest::anotherFunction :path: ../../examples/specific/class/xml - :no-link: .. doxygenfunction:: ClassTest::function :path: ../../examples/specific/class/xml - :no-link: .. doxygenfunction:: ClassTest::anotherFunction :path: ../../examples/specific/class/xml - :no-link: Alias Example ------------- +.. cpp:namespace:: @ex_specific_alias + .. doxygenfunction:: frob_foos :path: ../../examples/specific/alias/xml - :no-link: Fixed Width Font ---------------- +.. cpp:namespace:: @ex_specific_fixed_width + .. doxygenclass:: Out :path: ../../examples/specific/fixedwidthfont/xml :members: - :no-link: Function Overloads ------------------ +.. cpp:namespace:: @ex_specific_function_overloads + .. doxygenfunction:: f(int, int) :project: functionOverload - :no-link: .. doxygenfunction:: f(double, double) :project: functionOverload - :no-link: .. doxygenfunction:: test::g(int,int) :project: functionOverload - :no-link: .. doxygenfunction:: test::g(double, double) :project: functionOverload - :no-link: .. doxygenfunction:: h(std::string, MyType) :project: functionOverload - :no-link: .. doxygenfunction:: h(std::string, MyOtherType) :project: functionOverload - :no-link: .. doxygenfunction:: h(std::string, const int) :project: functionOverload - :no-link: .. doxygenfunction:: h(std::string, const T, const U) :project: functionOverload - :no-link: Program Listing --------------- +.. cpp:namespace:: @ex_specific_program_listing + .. doxygenclass:: Vector :project: programlisting - :no-link: .. doxygenfunction:: center :project: programlisting - :no-link: Image ----- +.. cpp:namespace:: @ex_specific_image + .. doxygenclass:: ImageClass :project: image - :no-link: - Array Parameter --------------- +.. this should be switch to the C domain, + as C++ does not support these array declarators + .. doxygenfunction:: foo :project: array - :no-link: .. doxygenfunction:: bar :project: array - :no-link: - C Enum ------ .. doxygenenum:: GSM_BackupFormat :project: c_enum - :no-link: - C Typedef --------- .. doxygenfile:: c_typedef.h :project: c_typedef - :no-link: C Typedef --------- .. doxygenfile:: define.h :project: define - :no-link: Multifile --------- +.. cpp:namespace:: @ex_specific_multifile + .. doxygenfunction:: TestTemplateFunction :project: multifile - :no-link: Interface Class --------------- +.. cpp:namespace:: @ex_specific_interface + .. doxygeninterface:: InterfaceClass :project: interface - :no-link: diff --git a/documentation/source/struct.rst b/documentation/source/struct.rst index 57921a9c..1b7ebd18 100644 --- a/documentation/source/struct.rst +++ b/documentation/source/struct.rst @@ -42,6 +42,8 @@ variable to set it in the ``conf.py``. Basic Example ------------- +.. cpp:namespace:: @ex_struct_basic + This displays the struct documentation without any members: .. code-block:: rst @@ -53,12 +55,13 @@ It produces this output: .. doxygenstruct:: StructTest :project: struct - :no-link: Members Example --------------- +.. cpp:namespace:: @ex_struct_members + This directive call will display the struct documentation with all the public members: @@ -73,12 +76,13 @@ It produces this output: .. doxygenstruct:: StructTest :project: struct :members: - :no-link: Specific Members Example ------------------------ +.. cpp:namespace:: @ex_struct_members_specific + This displays the struct documentation with only the members listed in the ``:members:`` option: @@ -93,12 +97,13 @@ It produces this output: .. doxygenstruct:: StructTest :project: struct :members: publicFunction, protectedFunction - :no-link: Protected Members ----------------- +.. cpp:namespace:: @ex_struct_members_protected + This displays only the protected members of the struct. Normally this is combined with the ``:members:`` option to show the public members as well. @@ -113,12 +118,13 @@ It produces this output: .. doxygenstruct:: StructTest :project: struct :protected-members: - :no-link: Private Members --------------- +.. cpp:namespace:: @ex_struct_members_private + This displays only the private members of the struct. Normally this is combined with the ``:members:`` option to show the public members as well. @@ -133,12 +139,13 @@ It produces this output: .. doxygenstruct:: StructTest :project: struct :private-members: - :no-link: Undocumented Members -------------------- +.. cpp:namespace:: @ex_struct_members_undocumented + This displays the undocumented members of the struct which are suppressed by default. Undocumented public members are only shown if the ``:members:`` option is also used. The same goes for the undocumented private members and the @@ -159,7 +166,6 @@ It produces this output: :members: :private-members: :undoc-members: - :no-link: .. note:: @@ -171,6 +177,8 @@ It produces this output: Outline Example --------------- +.. cpp:namespace:: @ex_struct_outline + This displays only the names of the struct members and not their documentation. The ``:members:`` and ``:private-members:`` options determine which members are displayed. @@ -188,12 +196,13 @@ It produces this output: :project: struct :members: :outline: - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_struct_failing + This intentionally fails: .. code-block:: rst diff --git a/documentation/source/template.rst b/documentation/source/template.rst index 928bb228..bfa3574e 100644 --- a/documentation/source/template.rst +++ b/documentation/source/template.rst @@ -1,6 +1,8 @@ Template ======== +.. cpp:namespace:: @ex_template_first + Breathe has support for class and function templates. They are output as follows. For a class with a single template parameter:: @@ -18,6 +20,8 @@ It renders as: ---- +.. cpp:namespace:: @ex_template_multiple + With multiple template parameters it renders as: ---- @@ -28,6 +32,8 @@ With multiple template parameters it renders as: ---- +.. cpp:namespace:: @ex_template_function_single + A function with single template parameter renders as: ---- @@ -37,6 +43,8 @@ A function with single template parameter renders as: ---- +.. cpp:namespace:: @ex_template_function_multiple + With multiple template parameters it renders as: ---- diff --git a/documentation/source/tinyxml.rst b/documentation/source/tinyxml.rst index e376fa65..38dce564 100644 --- a/documentation/source/tinyxml.rst +++ b/documentation/source/tinyxml.rst @@ -2,5 +2,7 @@ TinyXML Test Suite ================== +.. cpp:namespace:: @ex_tinyxml + .. doxygenindex:: diff --git a/documentation/source/typedef.rst b/documentation/source/typedef.rst index 13c732d0..f80cb1cb 100644 --- a/documentation/source/typedef.rst +++ b/documentation/source/typedef.rst @@ -7,6 +7,8 @@ doxygentypedef Directive Example Working Example --------------- +.. cpp:namespace:: @ex_typedef_example + This should work:: .. doxygentypedef:: UINT32 @@ -16,11 +18,12 @@ It produces this output: .. doxygentypedef:: UINT32 :project: structcmd - :no-link: Example with Namespace ---------------------- +.. cpp:namespace:: @ex_typedef_namespace + This should work:: .. doxygentypedef:: foo::ns::MyInt @@ -30,11 +33,12 @@ It produces this output: .. doxygentypedef:: foo::ns::MyInt :project: namespace - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_typedef_failing + This intentionally fails:: .. doxygentypedef:: made_up_typedef diff --git a/documentation/source/union.rst b/documentation/source/union.rst index 84d7cc16..4c993c26 100644 --- a/documentation/source/union.rst +++ b/documentation/source/union.rst @@ -7,6 +7,8 @@ doxygenunion Directive Example Working Example --------------- +.. cpp:namespace:: @ex_union_example + This should work:: .. doxygenunion:: SeparateUnion @@ -16,11 +18,12 @@ It produces this output: .. doxygenunion:: SeparateUnion :project: union - :no-link: Example with Namespace ---------------------- +.. cpp:namespace:: @ex_union_namespace + This should work:: .. doxygenunion:: foo::MyUnion @@ -30,11 +33,12 @@ It produces this output: .. doxygenunion:: foo::MyUnion :project: union - :no-link: Failing Example --------------- +.. cpp:namespace:: @ex_union_failing + This intentionally fails:: .. doxygenunion:: made_up_union diff --git a/documentation/source/variable.rst b/documentation/source/variable.rst index d8299349..adb1bc50 100644 --- a/documentation/source/variable.rst +++ b/documentation/source/variable.rst @@ -7,6 +7,8 @@ doxygenvariable Directive Example Working Example --------------- +.. cpp:namespace:: @ex_variable_example + This should work:: .. doxygenvariable:: global_cache_tree @@ -20,6 +22,8 @@ It produces this output: Failing Example --------------- +.. cpp:namespace:: @ex_variable_failing + This intentionally fails:: .. doxygenvariable:: made_up_variable From 2c34c14326056491d62cb1845399e636eeda81f8 Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Fri, 27 Mar 2020 11:09:31 +0100 Subject: [PATCH 08/11] Add specific tests for C to the documentation --- documentation/source/conf.py | 6 ++++-- documentation/source/specific.rst | 20 +++++++++++++++++++- examples/specific/Makefile | 5 +++-- examples/specific/c_macro.cfg | 11 +++++++++++ examples/specific/c_macro.h | 3 +++ examples/specific/c_struct.cfg | 11 +++++++++++ examples/specific/c_struct.h | 5 +++++ examples/specific/c_union.cfg | 11 +++++++++++ examples/specific/c_union.h | 5 +++++ 9 files changed, 72 insertions(+), 5 deletions(-) create mode 100644 examples/specific/c_macro.cfg create mode 100644 examples/specific/c_macro.h create mode 100644 examples/specific/c_struct.cfg create mode 100644 examples/specific/c_struct.h create mode 100644 examples/specific/c_union.cfg create mode 100644 examples/specific/c_union.h diff --git a/documentation/source/conf.py b/documentation/source/conf.py index 65115d21..f7dca1d5 100644 --- a/documentation/source/conf.py +++ b/documentation/source/conf.py @@ -208,8 +208,11 @@ "union":"../../examples/specific/union/xml/", "qtsignalsandslots":"../../examples/specific/qtsignalsandslots/xml/", "array":"../../examples/specific/array/xml/", + "c_struct":"../../examples/specific/c_struct/xml/", "c_enum":"../../examples/specific/c_enum/xml/", "c_typedef":"../../examples/specific/c_typedef/xml/", + "c_macro":"../../examples/specific/c_macro/xml/", + "c_union":"../../examples/specific/c_union/xml/", "define":"../../examples/specific/define/xml/", "multifile":"../../examples/specific/multifilexml/xml/", } @@ -228,8 +231,7 @@ breathe_domain_by_file_pattern = { "class.h" : "cpp", "alias.h" : "c", - "c_enum.h" : "c", - "c_typedef.h" : "c", + "c_*.h" : "c", } breathe_use_project_refids = True diff --git a/documentation/source/specific.rst b/documentation/source/specific.rst index 3acc0f2d..50ccad1e 100644 --- a/documentation/source/specific.rst +++ b/documentation/source/specific.rst @@ -118,6 +118,18 @@ Array Parameter .. doxygenfunction:: bar :project: array + +C Struct +-------- + +.. doxygenfile:: c_struct.h + :project: c_struct + +C Union +------- + +.. doxygenfile:: c_union.h + :project: c_union C Enum ------ @@ -131,7 +143,13 @@ C Typedef .. doxygenfile:: c_typedef.h :project: c_typedef -C Typedef +C Macro +------- + +.. doxygenfile:: c_macro.h + :project: c_macro + +C++ Macro --------- .. doxygenfile:: define.h diff --git a/examples/specific/Makefile b/examples/specific/Makefile index 1fadff9d..18e01cd0 100644 --- a/examples/specific/Makefile +++ b/examples/specific/Makefile @@ -18,12 +18,13 @@ DOCDIR = $(INSTALL)/share/doc/packages/doxygen QTDIR = HAVE_DOT = /usr/bin/dot -projects = nutshell alias rst inline namespacefile c_file array c_enum inheritance \ +projects = nutshell alias rst inline namespacefile array inheritance \ members userdefined fixedwidthfont latexmath functionOverload \ image name union group struct struct_function qtsignalsandslots lists \ headings links parameters template_class template_class_non_type \ template_function template_type_alias template_specialisation \ - enum c_typedef define interface + enum define interface \ + c_file c_struct c_enum c_typedef c_macro c_union special = programlisting decl_impl multifilexml auto class typedef diff --git a/examples/specific/c_macro.cfg b/examples/specific/c_macro.cfg new file mode 100644 index 00000000..c2e80684 --- /dev/null +++ b/examples/specific/c_macro.cfg @@ -0,0 +1,11 @@ +PROJECT_NAME = "C Macro" +OUTPUT_DIRECTORY = c_macro +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = c_macro.h +QUIET = YES +JAVADOC_AUTOBRIEF = YES +GENERATE_HTML = NO +GENERATE_XML = YES diff --git a/examples/specific/c_macro.h b/examples/specific/c_macro.h new file mode 100644 index 00000000..bf11ecd1 --- /dev/null +++ b/examples/specific/c_macro.h @@ -0,0 +1,3 @@ + +#define A_C_MACRO "hello world" +#define ANOTHER_C_MACRO(name) "hello" name diff --git a/examples/specific/c_struct.cfg b/examples/specific/c_struct.cfg new file mode 100644 index 00000000..19503363 --- /dev/null +++ b/examples/specific/c_struct.cfg @@ -0,0 +1,11 @@ +PROJECT_NAME = "C Struct" +OUTPUT_DIRECTORY = c_struct +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = c_struct.h +QUIET = YES +JAVADOC_AUTOBRIEF = YES +GENERATE_HTML = NO +GENERATE_XML = YES diff --git a/examples/specific/c_struct.h b/examples/specific/c_struct.h new file mode 100644 index 00000000..dda63937 --- /dev/null +++ b/examples/specific/c_struct.h @@ -0,0 +1,5 @@ + +struct ACStruct { + int i; +}; + diff --git a/examples/specific/c_union.cfg b/examples/specific/c_union.cfg new file mode 100644 index 00000000..46e54d45 --- /dev/null +++ b/examples/specific/c_union.cfg @@ -0,0 +1,11 @@ +PROJECT_NAME = "C Union" +OUTPUT_DIRECTORY = c_union +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_RTF = NO +CASE_SENSE_NAMES = NO +INPUT = c_union.h +QUIET = YES +JAVADOC_AUTOBRIEF = YES +GENERATE_HTML = NO +GENERATE_XML = YES diff --git a/examples/specific/c_union.h b/examples/specific/c_union.h new file mode 100644 index 00000000..491eb63d --- /dev/null +++ b/examples/specific/c_union.h @@ -0,0 +1,5 @@ + +union ACUnion { + int i; +}; + From 841022f700e66281c159f82a6b0e7a58c66d722d Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Tue, 7 Apr 2020 09:36:30 +0200 Subject: [PATCH 09/11] Makefile, make SPHINXOPTS overridable --- documentation/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/Makefile b/documentation/Makefile index c5f1fe9b..397a95f4 100644 --- a/documentation/Makefile +++ b/documentation/Makefile @@ -2,7 +2,7 @@ # # You can set these variables from the command line. -SPHINXOPTS = -vn +SPHINXOPTS ?= -vn SPHINXBUILD = sphinx-build PAPER = BUILDDIR ?= build From 01540d058eb49e5dbd9f6b0e77e5171f0583b3cc Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Tue, 7 Apr 2020 09:48:01 +0200 Subject: [PATCH 10/11] Reenable Python 3.5 test in workflows --- .github/workflows/unit_tests.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index 85c500d5..1e60ddcc 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -6,7 +6,7 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python-version: [3.6, 3.7, 3.8] + python-version: [3.5, 3.6, 3.7, 3.8] sphinx-version: - 3.0.0 - git+https://github.com/sphinx-doc/sphinx.git@3.0.x From 6083f29caf7dcce2d1aef23fc014edfe5083c4fe Mon Sep 17 00:00:00 2001 From: Jakob Lykke Andersen Date: Tue, 7 Apr 2020 09:50:35 +0200 Subject: [PATCH 11/11] ... and disable testing aginst Sphinx master --- .github/workflows/unit_tests.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index 1e60ddcc..fd0c9f27 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -11,7 +11,8 @@ jobs: - 3.0.0 - git+https://github.com/sphinx-doc/sphinx.git@3.0.x - git+https://github.com/sphinx-doc/sphinx.git@3.x - - git+https://github.com/sphinx-doc/sphinx.git@master + # master (Sphinx 4) will require at least Python 3.6, so disable it for now + #- git+https://github.com/sphinx-doc/sphinx.git@master steps: - uses: actions/checkout@v2