Sphinx 3 update

.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

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

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()
 
@@ -89,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 = {
@@ -117,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]]

documentation/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -vn
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR     ?= build

documentation/source/autofile.rst

@@ -22,4 +22,3 @@ It produces this output:
 
 .. autodoxygenfile:: auto_class.h
    :project: auto
-   :no-link:

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:
 

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

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:
 
@@ -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",
         }
 
@@ -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

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 <testnamespace::NamespacedClassT
 Inner Class Example
 -------------------
 
+.. cpp:namespace:: @ex_domains_inner_class
+
 Given the following Breathe directive::
 
    .. doxygenclass:: OuterClass
@@ -59,6 +63,8 @@ which renders as :cpp:class:`OuterClass::InnerClass`.
 Function Examples
 -----------------
 
+.. cpp:namespace:: @ex_domains_function
+
 Given the following Breathe directives::
 
    .. doxygenfunction:: testnamespace::NamespacedClassTest::function
@@ -99,6 +105,8 @@ which renders as: :c:func:`another reference <frob_foos()>`. 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