Repository: breathe-doc/breathe (language: python)

Issue:
C++20 concepts supported by doxygen v1.9.2+
I've been hunting errors in the docs build logs, and I found that the cpp-concept example (located in examples/specific) was not being properly parsed by doxygen in the CI. It is parsed as expected in doxygen v1.9.2 (&1.9.3) per local testing.

My error hunting goal is to make sphinx treat a warning as an error, thus making the doc building CI runs fail when new warnings have not been addressed. Due to this issue, we'd have to pin CI runs to doxygen v1.9.2 or newer (which can be done per #782 ). There is also a way to use conda forge to make RTD builds use a specific version of doxygen (despite the runner's frozen PPAs) which is a simple change in readthedocs.yaml.


Discussion / hints:

Fix patch:
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index d7d3afda2..0b3fea6b6 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -20,15 +20,28 @@ jobs:
       - name: install dependencies
         run: |
           pip install -r requirements/development.txt
-          sudo apt -y update
-          sudo apt -y install doxygen graphviz
+          sudo apt-get -y update
+          sudo apt-get -y install graphviz libclang1-9 libclang-cpp9
+
+      - name: install doxygen from SF binary archives
+        env:
+          DOXYGEN_VERSION: 1.9.4
+        run: |
+          mkdir doxygen-bin-arc && cd doxygen-bin-arc
+          curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz
+          gunzip doxygen.tar.gz
+          tar xf doxygen.tar
+          cd doxygen-$DOXYGEN_VERSION
+          sudo make install
 
       - name: build the documentation
         run: |
           make html
           rm documentation/build/html/.buildinfo
 
-      - uses: actions/upload-artifact@v1
+      - uses: actions/upload-artifact@v2
         with:
-          name: documentation
-          path: documentation/build/html
+          name: docs build artifacts
+          path: |
+            documentation/build/html
+            examples/*/*/xml
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
index 41f96c829..83ca91a4f 100644
--- a/.readthedocs.yaml
+++ b/.readthedocs.yaml
@@ -11,3 +11,6 @@ sphinx:
   builder: html
   configuration: documentation/source/conf.py
   fail_on_warning: false
+
+conda:
+  environment: documentation/environment.yaml
\ No newline at end of file
diff --git a/documentation/Makefile b/documentation/Makefile
index 397a95f40..cba3eb272 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -2,7 +2,9 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS   ?= -vn
+SPHINXOPTS   ?= -v -W -E
+# -n triggers an additional 100+ warnings (all about undefined references) that -W treats as errors.
+# these extraneous warnings are ignored because some doc pages have to avoid duplicate IDs
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR     ?= build
@@ -181,4 +183,3 @@ spelling:
 	$(SPHINXBUILD) -b spelling -N $(ALLSPHINXOPTS) $(BUILDDIR)/spelling
 	@echo
 	@echo "Build finished. The spelling files are in $(BUILDDIR)/spelling."
-
diff --git a/documentation/environment.yaml b/documentation/environment.yaml
new file mode 100644
index 000000000..1b8f9bcc4
--- /dev/null
+++ b/documentation/environment.yaml
@@ -0,0 +1,11 @@
+name: RTD
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  # doxygen versions available from conda forge are listed at
+  # https://anaconda.org/conda-forge/doxygen/files
+  # 
+  # - doxygen=1.9.4 # to specify a specific version of doxygen
+  # we'll be using the latest available
+  - doxygen
diff --git a/documentation/source/_static/breathe.css b/documentation/source/_static/breathe.css
index 292bc7f7d..5686b676f 100644
--- a/documentation/source/_static/breathe.css
+++ b/documentation/source/_static/breathe.css
@@ -3,11 +3,10 @@
 
 /* So enum value descriptions are displayed inline to the item */
 .breatheenumvalues li tt + p {
-	display: inline;
+  display: inline;
 }
 
 /* So parameter descriptions are displayed inline to the item */
 .breatheparameterlist li tt + p {
-	display: inline;
+  display: inline;
 }
-
diff --git a/documentation/source/autofile.rst b/documentation/source/autofile.rst
index f5a05af2e..2a4385db0 100644
--- a/documentation/source/autofile.rst
+++ b/documentation/source/autofile.rst
@@ -10,16 +10,20 @@ which is very similar to this directive.
 Working Example
 ---------------
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. autodoxygenfile:: auto_class.h
       :project: auto
 
-With the following config value::
+With the following config value:
+
+.. code-block:: python
 
    breathe_projects_source = {
-        "auto" : ( "../examples/specific", ["auto_class.h"] )
-        }
+       "auto" : ( "../examples/specific", ["auto_class.h"] )
+   }
 
 It produces this output:
 
diff --git a/documentation/source/autoindex.rst b/documentation/source/autoindex.rst
index fa12c2939..40060664a 100644
--- a/documentation/source/autoindex.rst
+++ b/documentation/source/autoindex.rst
@@ -7,16 +7,20 @@ autodoxygenindex Directive Example
 Working Example
 ---------------
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. autodoxygenindex::
       :project: auto
 
-With the following config value::
+With the following config value:
+
+.. code-block:: python
 
    breathe_projects_source = {
-        "auto" : ( "../examples/specific", ["auto_function.h", "auto_class.h"] )
-        }
+       "auto" : ( "../examples/specific", ["auto_function.h", "auto_class.h"] )
+   }
 
 It produces this output:
 
@@ -24,4 +28,3 @@ It produces this output:
 
 .. autodoxygenindex::
    :project: auto
-
diff --git a/documentation/source/class.rst b/documentation/source/class.rst
index e4d4f79d8..66d93bd55 100644
--- a/documentation/source/class.rst
+++ b/documentation/source/class.rst
@@ -119,7 +119,7 @@ It produces this output:
 .. doxygenclass:: Nutshell
    :project: nutshell
    :members:
-
+   :no-link:
 
 Specific Members Example
 ------------------------
@@ -133,14 +133,14 @@ This displays the class documentation with only the members listed in the
 
    .. doxygenclass:: Nutshell
       :project: nutshell
-      :members: crack, isCracked
+      :members: Tool, crack, isCracked
 
 It produces this output:
 
 .. doxygenclass:: Nutshell
    :project: nutshell
-   :members: crack, isCracked
-
+   :members: Tool, crack, isCracked
+   :no-link:
 
 Protected Members
 -----------------
@@ -182,6 +182,7 @@ It produces this output:
 .. doxygenclass:: Nutshell
    :project: nutshell
    :private-members:
+   :no-link:
 
 Undocumented Members
 --------------------
@@ -208,6 +209,7 @@ It produces this output:
    :members:
    :private-members:
    :undoc-members:
+   :no-link:
 
 .. note::
 
@@ -237,9 +239,12 @@ It produces this output:
    :project: membergroups
    :members:
    :membergroups: myGroup
+   :no-link:
 
 Without ``:membergroups: myGroup`` it would produce:
 
+.. cpp:namespace:: @ex_class_membergroups_all
+
 .. doxygenclass:: GroupedMembers
    :project: membergroups
    :members:
@@ -268,12 +273,16 @@ It produces this output:
    :project: classtest
    :members:
    :members-only:
+   :no-link:
 
 Without ``:members-only:`` it would produce:
 
+.. cpp:namespace:: @ex_class_members_all
+
 .. doxygenclass:: ClassTest
    :project: classtest
    :members:
+   :no-link:
 
 .. note::
 
@@ -286,11 +295,12 @@ Without ``:members-only:`` it would produce:
    In the ``readthedocs`` theme, the members will show up in the color scheme of the
    class definitions. If you would like them rendered as the other members,
    indent like above, create a ``_static/css/custom.css`` file containing
-   
+
    .. code-block:: css
 
       /* render as functions not classes when indented (for :members-only:) */
-      html.writer-html4 .rst-content blockquote dl:not(.field-list)>dt, html.writer-html5 .rst-content blockquote dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt {
+      html.writer-html4 .rst-content blockquote dl:not(.field-list)>dt,
+      html.writer-html5 .rst-content blockquote dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt {
         margin-bottom: 6px;
         border: none;
         border-left: 3px solid #ccc;
@@ -299,11 +309,11 @@ Without ``:members-only:`` it would produce:
       }
 
    and add the following to your ``conf.py``
-    
+
    .. code-block:: python
 
       html_static_path = ['_static']
-      
+
       html_css_files = ['css/custom.css']
 
 Outline Example
@@ -328,7 +338,7 @@ It produces this output:
    :project: nutshell
    :members:
    :outline:
-
+   :no-link:
 
 Qt Signals & Slots Example
 --------------------------
@@ -366,7 +376,6 @@ This intentionally fails:
 
 It produces the following warning message:
 
-.. warning:: doxygenclass: Cannot find class “made_up_class” in doxygen xml
+.. warning::
+   doxygenclass: Cannot find class “made_up_class” in doxygen xml
    output for project “class” from directory: ../../examples/doxygen/class/xml/
-
-
diff --git a/documentation/source/code/groups.h b/documentation/source/code/groups.h
index 87d1dfdea..7bba60f9e 100644
--- a/documentation/source/code/groups.h
+++ b/documentation/source/code/groups.h
@@ -1,7 +1,7 @@
 // Example from Doxygen documentation
 
 /** A class. More details about the Test class */
-class Test
+class UserDefinedGroupTest
 {
   public:
     //@{
@@ -17,17 +17,15 @@ class Test
     void func2InCustomGroup();
 };
 
-void Test::func1InGroup1() {}
-void Test::func2InGroup1() {}
+void UserDefinedGroupTest::func1InGroup1() {}
+void UserDefinedGroupTest::func2InGroup1() {}
 
 /** @name Custom Group
  *  Description of custom group
  */
 //@{
 /** Function 2 in custom group. Details. */
-void Test::func2InCustomGroup() {}
+void UserDefinedGroupTest::func2InCustomGroup() {}
 /** Function 1 in custom group. Details. */
-void Test::func1InCustomGroup() {}
+void UserDefinedGroupTest::func1InCustomGroup() {}
 //@}
-
-
diff --git a/documentation/source/codeguide.rst b/documentation/source/codeguide.rst
index e01a38048..658de4279 100644
--- a/documentation/source/codeguide.rst
+++ b/documentation/source/codeguide.rst
@@ -37,7 +37,9 @@ the other files that have been generated by doxygen and an indication of what
 they contain. 
 
 For example, in ``examples/doxygen/func/xml`` directory, the ``index.xml`` file
-contains::
+contains:
+
+.. code-block:: xml
 
    <?xml version='1.0' encoding='UTF-8' standalone='no'?>
    <doxygenindex xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="index.xsd" version="1.7.2">
@@ -228,8 +230,3 @@ code, the use of them is not something I've found very well documented and my
 code largely operates on a basis of trial and error. 
 
 One day I'm sure I'll be enlightened, until then expect fairly naive code.
-
-
-
-
-
diff --git a/documentation/source/concept.rst b/documentation/source/concept.rst
index 30ca25386..4bd2bc168 100644
--- a/documentation/source/concept.rst
+++ b/documentation/source/concept.rst
@@ -4,28 +4,44 @@
 doxygenconcept Directive Example
 ================================
 
+.. warning::
+   C++20 Concepts support was added in Doxygen v1.9.2. Please be sure to use Doxygen v1.9.2 or
+   newer with :ref:`doxygenconcept`.
+
 Working Example
 ---------------
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenconcept:: Hashable
       :project: cpp_concept
 
 It produces this output:
 
-.. doxygenconcept:: Hashable
-  :project: cpp_concept
+.. ifconfig:: doxygen_version < (1, 9, 2)
+
+   .. error::
+      The Doxygen version used to generate these docs does not support C++20 Concepts.
+      Please upgrade to using Doxygen v1.9.2 or newer.
+
+.. ifconfig:: doxygen_version > (1, 9, 1)
+
+   .. doxygenconcept:: Hashable
+      :project: cpp_concept
 
 Failing Example
 ---------------
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenconcept:: MadeUpConcept
       :project: cpp_concept
 
 It produces the following warning message:
 
-.. warning:: doxygenconcept: Cannot find concept "MadeUpConcept" in doxygen xml output
-
+.. warning::
+   doxygenconcept: Cannot find concept "MadeUpConcept" in doxygen xml output
diff --git a/documentation/source/conf.py b/documentation/source/conf.py
index 0c639eee9..a991fb543 100644
--- a/documentation/source/conf.py
+++ b/documentation/source/conf.py
@@ -34,6 +34,19 @@
 read_the_docs_build = os.environ.get("READTHEDOCS", None) == "True"
 travis_build = os.environ.get("TRAVIS_CI", None) == "True"
 
+# Get version of Doxygen and save it as a tuple
+
+doxygen_test = subprocess.run(["doxygen", "--version"], capture_output=True)
+if doxygen_test.returncode < 0:
+    raise RuntimeError(
+        "doxygen --version reported the following error:\n\t"
+        + str(doxygen_test.stderr, encoding="utf-8")
+    )
+doxygen_version = tuple(
+    int(x) for x in str(doxygen_test.stdout, encoding="utf-8").split()[0].split(".")
+)
+print("Using Doxygen v%d.%d.%d" % doxygen_version)
+
 # 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]
 
@@ -125,9 +138,7 @@
 # Set path for mathjax js to a https URL as sometimes the Breathe docs are displayed under https
 # and we can't load an http mathjax file from an https view of the docs. So we change to a https
 # mathjax file which we can load from http or https. We break the url over two lines.
-mathjax_path = (
-    "https://c328740.ssl.cf1.rackcdn.com/" "mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
-)
+mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS-MML_HTMLorMML"
 
 
 # Add any paths that contain templates here, relative to this directory.
@@ -401,3 +412,4 @@ def setup(app):
     app.connect("builder-inited", generate_doxygen_xml)
 
     app.add_config_value("documentation_build", "development", True)
+    app.add_config_value("doxygen_version", (0, 0, 0), "env")
diff --git a/documentation/source/credits.rst b/documentation/source/credits.rst
index 9a550da81..e28dd7e56 100644
--- a/documentation/source/credits.rst
+++ b/documentation/source/credits.rst
@@ -34,7 +34,6 @@ and working on the documentation. And thanks to:
 
 - Dimitri van Heesch for `Doxygen <http://www.stack.nl/~dimitri/doxygen/>`_.
 - Georg Brandl for `Sphinx <http://sphinx.pocoo.org>`_.
-- David Goodger for `Docutils <http://docutils.sourceforge.net/>`_ and reStructuredText. 
+- David Goodger for `Docutils <http://docutils.sourceforge.net/>`_ and reStructuredText.
 
 And thank you to whoever made the ``haiku`` theme for Sphinx.
-
diff --git a/documentation/source/customcss.rst b/documentation/source/customcss.rst
index 14c1795c7..fc710148a 100644
--- a/documentation/source/customcss.rst
+++ b/documentation/source/customcss.rst
@@ -9,17 +9,20 @@ classes to parts of the document. There are three such classes:
 
 **breatheparameterlist**
    Used to keep the description of a parameter displayed inline with the
-   parameter name. The Breathe docs use::
+   parameter name. The Breathe docs use:
+
+   .. code-block:: css
 
       .breatheparameterlist li tt + p {
-              display: inline;
+        display: inline;
       }
 
 **breatheenumvalues**
    Used to keep the description of an enum displayed inline with the
-   enum name. The Breathe docs use::
+   enum name. The Breathe docs use:
+
+   .. code-block:: css
 
       .breatheenumvalues li tt + p {
-              display: inline;
+        display: inline;
       }
-
diff --git a/documentation/source/define.rst b/documentation/source/define.rst
index b1ab70c92..68709a86a 100644
--- a/documentation/source/define.rst
+++ b/documentation/source/define.rst
@@ -7,7 +7,9 @@ doxygendefine Directive Example
 Working Example
 ---------------
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygendefine:: WRITE_TREE_MISSING_OK
       :project: c_file
@@ -20,13 +22,15 @@ It produces this output:
 Failing Example
 ---------------
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygendefine:: MADEUPDEFINE
       :project: define
 
 It produces the following warning message:
 
-.. warning:: doxygendefine: Cannot find define "MADEUPDEFINE" in doxygen xml
-             output for project "define" in directory: ../../examples/specific/define/xml
-
+.. warning::
+   doxygendefine: Cannot find define "MADEUPDEFINE" in doxygen xml
+   output for project "define" in directory: ../../examples/specific/define/xml
diff --git a/documentation/source/directives.rst b/documentation/source/directives.rst
index 3683fa4ad..226ace63f 100644
--- a/documentation/source/directives.rst
+++ b/documentation/source/directives.rst
@@ -34,15 +34,15 @@ The available directives are shown below. In each case the ``project``,
    should be used for this directive. This overrides the default project if one
    has been specified.
 
-   This is not used by the ``autodoxygenindex`` directive. Use ``source``
-   instead to specify the entry in the ``breathe_projects_source`` config value
+   This is not used by the `autodoxygenindex`_ directive. Use ``source``
+   instead to specify the entry in the :confval:`breathe_projects_source` config value
    to use.
 
 ``path``
    Directly specifies the path to the folder with the doxygen output. This
    overrides the project and default project if they have been specified.
 
-   This is not used by the ``autodoxygenindex`` directive. Use ``source-path``
+   This is not used by the `autodoxygenindex`_ directive. Use ``source-path``
    instead to specify the root path to the sources files which are to be
    processed.
 
@@ -72,7 +72,9 @@ doxygenclass
 This directive generates the appropriate output for a single class. It takes the
 standard ``project``, ``path``, ``outline`` and ``no-link`` options and
 additionally the ``members``, ``protected-members``, ``private-members``,
-``undoc-members``, ``membergroups`` and ``members-only`` options::
+``undoc-members``, ``membergroups`` and ``members-only`` options
+
+.. code-block:: rst
 
    .. doxygenclass:: <class name>
       :project: ...
@@ -96,9 +98,9 @@ doxygendefine
 ~~~~~~~~~~~~~
 
 This directive generates the appropriate output for a single preprocessor
-define. It behaves the same as the doxygenstruct directive.
+define. It behaves the same as the `doxygenstruct`_ directive.
 
-::
+.. code-block:: rst
 
    .. doxygendefine:: <define name>
       :project: ...
@@ -114,9 +116,9 @@ doxygenconcept
 ~~~~~~~~~~~~~~
 
 This directive generates the appropriate output for a single concept. It
-behaves the same as the doxygenstruct directive.
+behaves the same as the `doxygenstruct`_ directive.
 
-::
+.. code-block:: rst
 
    .. doxygenconcept:: <concept name>
       :project: ...
@@ -132,9 +134,9 @@ doxygenenum
 ~~~~~~~~~~~
 
 This directive generates the appropriate output for a single enum. It behaves
-the same as the doxygenstruct directive.
+the same as the `doxygenstruct`_ directive.
 
-::
+.. code-block:: rst
 
    .. doxygenenum:: <enum name>
       :project: ...
@@ -151,7 +153,7 @@ doxygenenumvalue
 
 This directive generates the appropriate output for a single enum value.
 
-::
+.. code-block:: rst
 
    .. doxygenenumvalue:: <enum value name>
       :project: ...
@@ -169,7 +171,7 @@ doxygenfile
 This directive generates the appropriate output for the contents of a source
 file.
 
-::
+.. code-block:: rst
 
    .. doxygenfile:: <filename>
       :project: ...
@@ -186,10 +188,10 @@ Checkout the :ref:`example <file-example>` to see it in action.
 autodoxygenfile
 ~~~~~~~~~~~~~~~
 
-This directive is this ``auto`` version of the doxygenfile directive above.
+This directive is this ``auto`` version of the `doxygenfile`_ directive above.
 It handles the doxygen xml generation for you like the other auto directives.
 
-::
+.. code-block:: rst
 
    .. autodoxygenfile:: <filename>
       :project: ...
@@ -208,7 +210,7 @@ doxygenfunction
 This directive generates the appropriate output for a single function. The
 function name is required to be unique in the project.
 
-::
+.. code-block:: rst
 
    .. doxygenfunction:: <function name>
       :project: ...
@@ -231,7 +233,7 @@ It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
 and additionally the ``content-only``, ``desc-only``, ``members``,
 ``protected-members``, ``private-members`` and ``undoc-members`` options.
 
-::
+.. code-block:: rst
 
    .. doxygengroup:: <group name>
       :project: ...
@@ -261,7 +263,7 @@ This directive processes and produces output for everything described by the
 Doxygen xml output. It reads the ``index.xml`` file and process everything
 referenced by it.
 
-::
+.. code-block:: rst
 
    .. doxygenindex::
       :project: ...
@@ -275,22 +277,22 @@ referenced by it.
 autodoxygenindex
 ~~~~~~~~~~~~~~~~
 
-This directive performs a similar role to the ``doxygenindex`` directive except
+This directive performs a similar role to the `doxygenindex`_ directive except
 that it handles the doxygen xml generation for you. It uses the
-``breathe_projects_source`` configuration dictionary to judge which code source
+:confval:`breathe_projects_source` configuration dictionary to judge which code source
 files should have doxygen xml generated for them. The ``project`` directive
 option associates the directive with a particular project in the
-``breathe_projects_source`` dictionary. All the files references by the entry in
-the ``breathe_projects_source`` will be included in the output. In addition, any
-options specified in ``breathe_doxygen_config_options`` will be added to the
+:confval:`breathe_projects_source` dictionary. All the files references by the entry in
+the :confval:`breathe_projects_source` will be included in the output. In addition, any
+options specified in :confval:`breathe_doxygen_config_options` will be added to the
 generated Doxygen config file and any custom aliases specified in
-``breathe_doxygen_config_aliases`` will be added to the `doxygen aliases
+:confval:`breathe_doxygen_aliases` will be added to the `doxygen aliases
 <https://www.doxygen.nl/manual/custcmd.html>`_.
 
 Thank you to `Scopatz <https://github.com/scopatz>`_ for the idea and initial
 implementation.
 
-::
+.. code-block:: rst
 
    .. autodoxygenindex::
       :project: ...
@@ -314,7 +316,7 @@ and additionally the ``content-only``, ``desc-only``, ``members``,
 To reference a nested namespace, the full namespaced path must be provided, e.g.
 ``foo::bar`` for the ``bar`` namespace inside the ``foo`` namespace.
 
-::
+.. code-block:: rst
 
    .. doxygennamespace:: <namespace>
       :project: ...
@@ -343,7 +345,7 @@ It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
 and additionally the ``members``, ``protected-members``, ``private-members``,
 ``membergroups``, ``members-only`` and ``undoc-members`` options.
 
-::
+.. code-block:: rst
 
    .. doxygenstruct:: <struct name>
       :project: ...
@@ -366,9 +368,9 @@ doxygeninterface
 ~~~~~~~~~~~~~~~~
 
 This directive generates the appropriate output for a single interface (specially-used
-class). It behaves the same as the doxygenclass directive.
+class). It behaves the same as the `doxygenclass`_ directive.
 
-::
+.. code-block:: rst
 
    .. doxygeninterface:: <interface name>
       :project: ...
@@ -390,7 +392,7 @@ doxygentypedef
 This directive generates the appropriate output for a single typedef. It behaves
 the same as the doxygenstruct directive.
 
-::
+.. code-block:: rst
 
    .. doxygentypedef:: <typedef name>
       :project: ...
@@ -408,7 +410,7 @@ doxygenunion
 This directive generates the appropriate output for a single union. It behaves
 the same as the doxygenstruct directive.
 
-::
+.. code-block:: rst
 
    .. doxygenunion:: <union name>
       :project: ...
@@ -426,7 +428,7 @@ doxygenvariable
 This directive generates the appropriate output for a single variable.
 It behaves the same as the doxygenstruct directive.
 
-::
+.. code-block:: rst
 
    .. doxygenvariable:: <variable name>
       :project: ...
@@ -449,7 +451,7 @@ for markup in the source comments. For more information check the
 It takes the standard ``project`` and ``path`` options and additionally the
 ``content-only`` option.
 
-::
+.. code-block:: rst
 
    .. doxygenpage:: <page name>
       :project: ...
@@ -484,17 +486,21 @@ Config Values
    Allows you to specify domains for particular files according to their
    extension.
 
-   For example::
+   For example:
+
+   .. code-block:: python
 
       breathe_domain_by_extension = {
-              "h" : "cpp",
-              }
+          "h" : "cpp",
+      }
 
-   You can also use this to enable support for Doxygen XML generated from PHP code::
+   You can also use this to enable support for Doxygen XML generated from PHP code:
+
+   .. code-block:: python
 
       breathe_domain_by_extension = {
-              "php" : "php",
-              }
+          "php" : "php",
+      }
 
 .. confval:: breathe_domain_by_file_pattern
 
@@ -502,11 +508,13 @@ Config Values
    is checked after :confval:`breathe_domain_by_extension` and so will override
    it when necessary.
 
-   For example::
+   For example:
+
+   .. code-block:: python
 
       breathe_domain_by_file_pattern = {
-              "\*/alias.h" : "c",
-              }
+          "\*/alias.h" : "c",
+      }
 
    If you wanted all ``.h`` header files to be treated as being in the **cpp**
    domain you might use the :confval:`breathe_domain_by_extension` example
@@ -519,19 +527,26 @@ Config Values
    A dictionary in which the keys are project names and the values are a tuple
    of the directory and a list of file names of the source code for those
    projects that you would like to be automatically processed with doxygen.
-   If you have some files in::
+   If you have some files in:
+   
+   .. code-block:: text
 
       /some/long/path/to/myproject/file.c
       /some/long/path/to/myproject/subfolder/otherfile.c
 
-   Then you can set::
+   Then you can set:
+
+   .. code-block:: python
 
       breathe_projects_source = {
-         "myprojectsource" :
-             ( "/some/long/path/to/myproject", [ "file.c", "subfolder/otherfile.c" ] )
-         }
+          "myprojectsource" : (
+              "/some/long/path/to/myproject", ["file.c", "subfolder/otherfile.c"]
+          )
+      }
 
-   Then your ``autodoxygenfile`` usage can look like this::
+   Then your `autodoxygenfile`_ usage can look like this:
+
+   .. code-block:: rst
 
       .. autodoxygenfile:: file.c
          :project: myprojectsource
@@ -541,7 +556,7 @@ Config Values
 
 .. confval:: breathe_build_directory
 
-   In order to process the ``autodoxygenindex`` Breathe has to run ``doxygen``
+   In order to process the `autodoxygenindex`_ Breathe has to run ``doxygen``
    to create the xml files for processing. This config value specifies the root
    directory that these files should be created in. By default, this is set to
    the parent directory of the ``doctrees`` output folder which is the normal
@@ -559,7 +574,9 @@ Config Values
    take ``:members:``, ``:private-members:`` and ``:undoc-members:`` options.
    By default, this is set to an empty list, which means no members are
    displayed. If you'd like to always display the public and public,
-   undocumented members then you could set it like this::
+   undocumented members then you could set it like this:
+
+   .. code-block:: python
 
       breathe_default_members = ('members', 'undoc-members')
 
@@ -568,14 +585,16 @@ Config Values
 .. confval:: breathe_implementation_filename_extensions
 
    Provides a list of the filename extensions which are considered to be
-   implementation files. These files are ignored when the ``doxygenfunction``
-   directive looks for unnamespaced function names. This is to avoid the issue
+   implementation files. These files are ignored when the `doxygenfunction`_
+   directive looks for un-namespaced function names. This is to avoid the issue
    where the same function name appears in the doxygen XML output for a header
    file and implementation file because the declaration is in one and the
    definition is in the other. Doxygen appends the documentation from the
    definition to the XML for the declaration so we don't miss any documentation
    information from the implementation files. The default value for this
-   variable is::
+   variable is:
+
+   .. code-block:: python
 
       breathe_implementation_filename_extensions = ['.c', '.cc', '.cpp']
 
@@ -585,7 +604,9 @@ Config Values
 
    A dictionary in which the keys and values are the names and values of config
    options to be placed in the Doxygen config file generated by
-   ``autodoxygenindex``. For instance, this::
+   `autodoxygenindex`_. For instance, this:
+
+   .. code-block:: python
 
       breathe_doxygen_config_options = {'EXCLUDE_SYMBOLS': 'abc123'}
 
@@ -594,20 +615,24 @@ Config Values
 
 .. confval:: breathe_doxygen_aliases
 
-    A dictionnary in which the keys and values are the names and values of aliases
-    to be placed in the Doxygen config file generated by ``autodoxygenindex``.
-    For instance, this::
+   A dictionary in which the keys and values are the names and values of aliases
+   to be placed in the Doxygen config file generated by `autodoxygenindex`_.
+   For instance, this:
+
+   .. code-block:: python
 
-      breathe_doxygen_aliases = {'rstref{1}': r'\verbatim embed:rst:inline :ref:`\1` \endverbatim'}
+      breathe_doxygen_aliases = {
+          'rstref{1}': r'\verbatim embed:rst:inline :ref:`\1` \endverbatim'
+      }
 
-    would place the line::
+   would place the line::
 
       ALIASES += rstref{1}="\verbatim embed:rst:inline :ref:`\1` \endverbatim"
 
-    in the config file. The default value is an empty dictionary.
-    Note the use of a raw string to ensure that backslashes are interpreted as literal characters.
-    (This example alias enables linking to rst targets inline in doxygen comments using
-    ``\rstref{<target_name>}``)
+   in the config file. The default value is an empty dictionary.
+   Note the use of a raw string to ensure that backslashes are interpreted as literal characters.
+   (This example alias enables linking to rst targets inline in doxygen comments using
+   ``\rstref{<target_name>}``)
 
 .. confval:: breathe_show_define_initializer
 
diff --git a/documentation/source/domains.rst b/documentation/source/domains.rst
index cd0452aa5..84db79ca3 100644
--- a/documentation/source/domains.rst
+++ b/documentation/source/domains.rst
@@ -17,25 +17,31 @@ Class Example
 
 .. cpp:namespace:: @ex_domains_class
 
-Given the following Breathe directives::
+Given the following Breathe directives:
 
-   .. doxygenclass:: testnamespace::NamespacedClassTest
+.. code-block:: rst
+
+   .. doxygenclass:: TestNamespaceClasses::NamespacedClassTest
       :path: ../../examples/specific/class/xml
 
 Which create formatted output like:
 
-   .. doxygenclass:: testnamespace::NamespacedClassTest
+   .. doxygenclass:: TestNamespaceClasses::NamespacedClassTest
       :path: ../../examples/specific/class/xml
 
-We can refer to **NamespacedClassTest** using:: 
+We can refer to **NamespacedClassTest** using:
+
+.. code-block:: rst
+
+   :cpp:class:`TestNamespaceClasses::NamespacedClassTest`
 
-   :cpp:class:`testnamespace::NamespacedClassTest`
-   
-which renders as :cpp:class:`testnamespace::NamespacedClassTest`, or using::
+which renders as :cpp:class:`TestNamespaceClasses::NamespacedClassTest`, or using:
 
-   :cpp:class:`another reference <testnamespace::NamespacedClassTest>`
-   
-which renders as: :cpp:class:`another reference <testnamespace::NamespacedClassTest>`.
+.. code-block:: rst
+
+   :cpp:class:`another reference <TestNamespaceClasses::NamespacedClassTest>`
+
+which renders as: :cpp:class:`another reference <TestNamespaceClasses::NamespacedClassTest>`.
 
 Inner Class Example
 -------------------
@@ -57,7 +63,7 @@ Which create formatted output like:
 We can refer to **OuterClass::InnerClass** using::
 
    :cpp:class:`OuterClass::InnerClass`
-   
+
 which renders as :cpp:class:`OuterClass::InnerClass`.
 
 Function Examples
@@ -65,9 +71,11 @@ Function Examples
 
 .. cpp:namespace:: @ex_domains_function
 
-Given the following Breathe directives::
+Given the following Breathe directives:
 
-   .. doxygenfunction:: testnamespace::NamespacedClassTest::function
+.. code-block:: rst
+
+   .. doxygenfunction:: TestNamespaceClasses::NamespacedClassTest::function
       :path: ../../examples/specific/class/xml
 
    .. doxygenfunction:: frob_foos
@@ -75,31 +83,39 @@ Given the following Breathe directives::
 
 Which create formatted output like:
 
-   .. doxygenfunction:: testnamespace::NamespacedClassTest::function
+   .. doxygenfunction:: TestNamespaceClasses::NamespacedClassTest::function
       :path: ../../examples/specific/class/xml
 
    .. doxygenfunction:: frob_foos
       :path: ../../examples/specific/alias/xml
 
-We can refer to **function** using:: 
+We can refer to **namespaceFunc** using:
+
+.. code-block:: rst
+
+   :cpp:func:`TestNamespaceFunction::namespaceFunc()`
 
-   :cpp:func:`testnamespace::NamespacedClassTest::function()`
-   
-which renders as :cpp:func:`testnamespace::NamespacedClassTest::function()`, or using::
+which renders as :cpp:func:`TestNamespaceFunction::namespaceFunc()`, or using:
 
-   :cpp:func:`another reference <testnamespace::NamespacedClassTest::function()>`
-   
-which renders as: :cpp:func:`another reference <testnamespace::NamespacedClassTest::function()>`.
+.. code-block:: rst
+
+   :cpp:func:`another reference <namespaceFunc()>`
+
+which renders as: :cpp:func:`another reference <TestNamespaceFunction::namespaceFunc()>`.
 Note the use of the **cpp** domain.
 
-And we can refer to **frob_foos** using:: 
-   
+And we can refer to **frob_foos** using:
+
+.. code-block:: rst
+
    :c:func:`frob_foos()`
 
-which renders as: :c:func:`frob_foos()`, or using::
+which renders as: :c:func:`frob_foos()`, or using:
+
+.. code-block:: rst
+
+   :c:func:`another reference <frob_foos()>`
 
-   :c:func:`another reference <frob_foos()>` 
-   
 which renders as: :c:func:`another reference <frob_foos()>`. Note the use of the **c** domain.
 
 Typedef Examples
@@ -107,12 +123,14 @@ Typedef Examples
 
 .. cpp:namespace:: @ex_domains_typedef
 
-Given the following Breathe directives::
+Given the following Breathe directives:
+
+.. code-block:: rst
 
    .. doxygentypedef:: TestTypedef
       :path: ../../examples/specific/typedef/xml
 
-   .. doxygentypedef:: testnamespace::AnotherTypedef
+   .. doxygennamespace:: TypeDefNamespace
       :path: ../../examples/specific/typedef/xml
 
    .. doxygenclass:: TestClass
@@ -124,22 +142,28 @@ which create formatted output like:
    .. doxygentypedef:: TestTypedef
       :path: ../../examples/specific/typedef/xml
 
-   .. doxygentypedef:: testnamespace::AnotherTypedef
+   .. doxygennamespace:: TypeDefNamespace
       :path: ../../examples/specific/typedef/xml
 
    .. doxygenclass:: TestClass
       :path: ../../examples/specific/typedef/xml
       :members:
 
-We can refer to **TestTypedef** using::
+We can refer to **TestTypedef** using:
+
+.. code-block:: rst
 
    :cpp:type:`TestTypedef`
-   
-which renders as :cpp:type:`TestTypedef`, to **testnamespace::AnotherTypedef** using::
 
-   :cpp:type:`testnamespace::AnotherTypedef`
+which renders as :cpp:type:`TestTypedef`, to **TypeDefNamespace::AnotherTypedef** using:
+
+.. code-block:: rst
 
-which renders as :cpp:type:`testnamespace::AnotherTypedef` and to **TestClass::MemberTypedef** using::
+   :cpp:type:`TypeDefNamespace::AnotherTypedef`
+
+which renders as :cpp:type:`TypeDefNamespace::AnotherTypedef` and to **TestClass::MemberTypedef** using:
+
+.. code-block:: rst
 
    :cpp:type:`TestClass::MemberTypedef`
 
@@ -150,12 +174,14 @@ Enum Value Examples
 
 .. cpp:namespace:: @ex_domains_enum
 
-Given the following Breathe directives::
+Given the following Breathe directives:
+
+.. code-block:: rst
 
    .. doxygenenumvalue:: VALUE
       :path: ../../examples/specific/enum/xml
 
-   .. doxygenenumvalue:: testnamespace::FIRST
+   .. doxygenenumvalue:: TestEnumNamespace::FIRST
       :path: ../../examples/specific/enum/xml
 
 Which create formatted output like:
@@ -163,15 +189,19 @@ Which create formatted output like:
    .. doxygenenumvalue:: VALUE
       :path: ../../examples/specific/enum/xml
 
-   .. doxygenenumvalue:: testnamespace::FIRST
+   .. doxygenenumvalue:: TestEnumNamespace::FIRST
       :path: ../../examples/specific/enum/xml
 
-We can refer to **VALUE** using::
+We can refer to **VALUE** using:
+
+.. code-block:: rst
 
    :cpp:enumerator:`VALUE`
-   
-which renders as :cpp:enumerator:`VALUE` and to **testnamespace::FIRST** using ::
 
-   :cpp:enumerator:`testnamespace::FIRST`
+which renders as :cpp:enumerator:`VALUE` and to **TestEnumNamespace::FIRST** using:
+
+.. code-block:: rst
+
+   :cpp:enumerator:`TestEnumNamespace::FIRST`
 
-which renders as :cpp:enumerator:`testnamespace::FIRST`.
+which renders as :cpp:enumerator:`TestEnumNamespace::FIRST`.
diff --git a/documentation/source/doxygen.rst b/documentation/source/doxygen.rst
index 19705d482..c25d2fbee 100644
--- a/documentation/source/doxygen.rst
+++ b/documentation/source/doxygen.rst
@@ -217,13 +217,6 @@ PyExample
 .. doxygenindex::
    :path: ../../examples/doxygen/pyexample/xml
 
-Mux
----
-
-.. cpp:namespace:: @ex_doxygen_mux
-
-.. doxygenindex::
-   :path: ../../examples/doxygen/mux/xml
 
 Manual
 ------
diff --git a/documentation/source/enum.rst b/documentation/source/enum.rst
index 43d1ce8ae..840656e3c 100644
--- a/documentation/source/enum.rst
+++ b/documentation/source/enum.rst
@@ -9,7 +9,9 @@ Working Example
 
 .. cpp:namespace:: @ex_enum_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenenum:: NodeType
       :project: tinyxml
@@ -24,7 +26,9 @@ Example with Namespace
 
 .. cpp:namespace:: @ex_enum_namespace
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenenum:: foo::ns::Letters
       :project: namespace
@@ -39,12 +43,14 @@ Failing Example
 
 .. cpp:namespace:: @ex_enum_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenenum:: made_up_enum
       :project: restypedef
 
 It produces the following warning message:
 
-.. warning:: doxygenenum: Cannot find enum "made_up_enum" in doxygen xml output
-
+.. warning::
+   doxygenenum: Cannot find enum "made_up_enum" in doxygen xml output
diff --git a/documentation/source/enumvalue.rst b/documentation/source/enumvalue.rst
index ae05cf0dd..74bc06086 100644
--- a/documentation/source/enumvalue.rst
+++ b/documentation/source/enumvalue.rst
@@ -9,7 +9,9 @@ Working Example
 
 .. cpp:namespace:: @ex_enumvalue_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenenumvalue:: TIXML_NO_ERROR
       :project: tinyxml
@@ -24,7 +26,9 @@ Example with Namespace
 
 .. cpp:namespace:: @ex_enumvalue_namespace
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenenumvalue:: foo::ns::A
       :project: namespace
@@ -39,12 +43,14 @@ Failing Example
 
 .. cpp:namespace:: @ex_enumvalue_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenenumvalue:: made_up_enumvalue
       :project: restypedef
 
 It produces the following warning message:
 
-.. warning:: doxygenenumvalue: Cannot find enumvalue "made_up_enumvalue" in doxygen xml output
-
+.. warning::
+   doxygenenumvalue: Cannot find enumvalue "made_up_enumvalue" in doxygen xml output
diff --git a/documentation/source/examples/codeblocks.rst b/documentation/source/examples/codeblocks.rst
deleted file mode 100644
index f09d78748..000000000
--- a/documentation/source/examples/codeblocks.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-
-Examples: Code Blocks
-=====================
-
-The following should render with standard C/C++ highlighting.
-
-.. doxygenfunction:: with_standard_code_block
-   :path: ../../examples/specific/code_blocks/xml
-   :no-link:
-
-The following should render with no detected highlighting.
-
-.. doxygenfunction:: with_unannotated_cmake_code_block
-   :path: ../../examples/specific/code_blocks/xml
-   :no-link:
-
-The following should render with specified cmake highlighting.
-
-.. doxygenfunction:: with_annotated_cmake_code_block
-   :path: ../../examples/specific/code_blocks/xml
-   :no-link:
diff --git a/documentation/source/file.rst b/documentation/source/file.rst
index 11c103f5a..cb377de8c 100644
--- a/documentation/source/file.rst
+++ b/documentation/source/file.rst
@@ -69,7 +69,9 @@ Example
 
 .. cpp:namespace:: @ex_file_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenfile:: nutshell.h
       :project: nutshell
@@ -87,7 +89,9 @@ Example with Selected and Ordered Sections
 .. cpp:namespace:: @ex_file_section
 
 The following will only show the **briefdescription** and **public-type**
-sections, in that order::
+sections, in that order:
+
+.. code-block:: rst
 
    .. doxygenfile:: nutshell.h
       :project: nutshell
@@ -100,13 +104,16 @@ It produces this output:
 .. doxygenfile:: nutshell.h
    :project: nutshell
    :sections: briefdescription innerclass public-type
+   :no-link:
 
 Example with Nested Namespaces
 ------------------------------
 
 .. cpp:namespace:: @ex_file_namespace
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenfile:: namespacefile.h
       :project: namespace
@@ -126,12 +133,16 @@ Example for 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::
+following two files:
+
+.. code-block:: text
 
    /some/long/project/path/parser/Util.h
    /some/long/project/path/finder/Util.h
 
-You should specify::
+You should specify:
+
+.. code-block:: rst
 
    .. doxygenfile:: parser/Util.h
 
@@ -144,11 +155,14 @@ Failing Example
 
 .. cpp:namespace:: @ex_file_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenfile:: made_up_file.h
       :project: nutshell
 
 It produces the following warning message:
 
-.. warning:: Cannot find file "made_up_file.h" in doxygen xml output for project "nutshell" from directory: ../../examples/specific/nutshell/xml/
+.. warning::
+   Cannot find file "made_up_file.h" in doxygen xml output for project "nutshell" from directory: ../../examples/specific/nutshell/xml/
diff --git a/documentation/source/function.rst b/documentation/source/function.rst
index 244208e42..4f2f1bf28 100644
--- a/documentation/source/function.rst
+++ b/documentation/source/function.rst
@@ -20,7 +20,9 @@ Working Example
 
 .. cpp:namespace:: @ex_function_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenfunction:: open
       :project: structcmd
@@ -35,7 +37,9 @@ Separated Declaration & Implementation Example
 
 .. cpp:namespace:: @ex_function_separated
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenfunction:: open_di
       :project: decl_impl
@@ -50,12 +54,14 @@ Failing Example
 
 .. cpp:namespace:: @ex_function_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenfunction:: made_up_function
       :project: structcmd
 
 It produces the following warning message:
 
-.. warning:: doxygenfunction: Cannot find function "made_up_function" in doxygen xml output
-
+.. warning::
+   doxygenfunction: Cannot find function "made_up_function" in doxygen xml output
diff --git a/documentation/source/group.rst b/documentation/source/group.rst
index 5bd841d04..32de5c720 100644
--- a/documentation/source/group.rst
+++ b/documentation/source/group.rst
@@ -44,7 +44,7 @@ options.
 
 If you would like to always specify some combination of ``members``,
 ``protected-members``, ``private-members`` and ``undoc-members`` then you can
-use the :ref:`breathe_default_members <breathe-default-members>` configuration
+use the :confval:`breathe_default_members` configuration
 variable to set it in the ``conf.py``.
 
 ``inner``
@@ -94,11 +94,12 @@ Produces this output:
 .. doxygengroup:: mygroup
    :project: group
    :content-only:
+   :no-link:
 
 .. note::
 
    As you can see from the output, section headings like 'Functions' are missing
-   from the :content-only: display. This is due to an implementation detail. If
+   from the ``:content-only:`` display. This is due to an implementation detail. If
    post an issue on github if you'd like it addressed.
 
 
@@ -112,7 +113,7 @@ classes. The output for any class in the group should be the same as if it had
 be produced by the :ref:`doxygenclass directive <class-example>` with the
 ``members`` option specified.
 
-::
+.. code-block:: rst
 
    .. doxygengroup:: mygroup
       :project: group
@@ -123,7 +124,7 @@ It produces this output:
 .. doxygengroup:: mygroup
    :project: group
    :members:
-
+   :no-link:
 
 Protected Members Example
 -------------------------
@@ -135,7 +136,7 @@ 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 <class-example>`
 with the ``protected-members`` option specified.
 
-::
+.. code-block:: rst
 
    .. doxygengroup:: mygroup
       :project: group
@@ -146,7 +147,7 @@ It produces this output:
 .. doxygengroup:: mygroup
    :project: group
    :protected-members:
-
+   :no-link:
 
 Private-Members Example
 -----------------------
@@ -169,7 +170,7 @@ Produces this output:
 .. doxygengroup:: mygroup
    :project: group
    :private-members:
-
+   :no-link:
 
 Undocumented Members Example
 ----------------------------
@@ -193,6 +194,7 @@ Produces this output:
    :project: group
    :private-members:
    :undoc-members:
+   :no-link:
 
 .. note::
 
@@ -219,7 +221,7 @@ Produces this output:
 .. doxygengroup:: mygroup
    :project: group
    :inner:
-
+   :no-link:
 
 Outline Example
 ---------------
@@ -242,7 +244,7 @@ It produces this output:
    :project: group
    :members:
    :outline:
-
+   :no-link:
 
 Failing Example
 ---------------
@@ -258,6 +260,6 @@ This intentionally fails:
 
 It produces the following warning message:
 
-.. warning:: Cannot find file "madeupgroup" in doxygen xml output for project
-             "group" from directory: ../../examples/specific/group/xml/
-
+.. warning::
+   Cannot find file "madeupgroup" in doxygen xml output for project
+   "group" from directory: ../../examples/specific/group/xml/
diff --git a/documentation/source/groups.rst b/documentation/source/groups.rst
index 2c172dfac..cf1ebce50 100644
--- a/documentation/source/groups.rst
+++ b/documentation/source/groups.rst
@@ -11,16 +11,18 @@ Using the example from the Doxygen docs:
 .. literalinclude:: code/groups.h
    :language: cpp
 
-If we reference this with a directive, for example::
+If we reference this with a directive, for example:
 
-   .. doxygenclass:: Test
+.. code-block:: rst
+
+   .. doxygenclass:: UserDefinedGroupTest
       :project: userdefined
       :members:
       :protected-members:
 
 It renders as:
 
-.. doxygenclass:: Test
+.. doxygenclass:: UserDefinedGroupTest
    :project: userdefined
    :members:
    :protected-members:
@@ -31,5 +33,3 @@ It renders as:
    Any groups which are not named in the original source code will appear as
    **Unnamed Group** in the final output. This is different to Doxygen which
    will number the groups and so name them as Group1, Group2, Group3, etc.
-
-
diff --git a/documentation/source/index.rst b/documentation/source/index.rst
index 6ef869086..45995253c 100644
--- a/documentation/source/index.rst
+++ b/documentation/source/index.rst
@@ -1,4 +1,5 @@
-.. BreatheExample documentation master file, created by sphinx-quickstart on Tue Feb  3 18:20:48 2009.
+..
+   BreatheExample documentation master file, created by sphinx-quickstart on Tue Feb  3 18:20:48 2009.
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
@@ -114,29 +115,39 @@ You write code that looks a little like this:
 .. literalinclude:: code/nutshell.h
    :language: cpp
 
-Then you run this::
+Then you run this:
+
+.. code-block:: text
 
    doxygen
 
-With a setting that says this::
+With a setting that says this:
+
+.. code-block:: text
 
    GENERATE_XML = YES
 
-Then in your Sphinx documentation, you add something like this::
+Then in your Sphinx documentation, you add something like this:
+
+.. code-block:: rst
 
    .. doxygenclass:: Nutshell
       :project: nutshell
       :members:
 
-With a ``conf.py`` setting like this::
+With a ``conf.py`` setting like this:
+
+.. code-block:: python
 
    breathe_projects = {
-       "nutshell":"../../examples/specific/nutshell/xml/",
-       }
+       "nutshell": "../../examples/specific/nutshell/xml/",
+   }
+
+And Breathe registered as an extension in ``conf.py`` like this:
 
-And Breathe registered as an extension in ``conf.py`` like this::
+.. code-block:: rst
 
-   extensions = [ "breathe" ]
+   extensions = ["breathe"]
 
 You get something like this:
 
diff --git a/documentation/source/latexmath.rst b/documentation/source/latexmath.rst
index 3f65211c1..12a04f897 100644
--- a/documentation/source/latexmath.rst
+++ b/documentation/source/latexmath.rst
@@ -3,7 +3,9 @@ Latex Math
 ==========
 
 Breathe has basic support for latex math markup in the doxygen comments.  A
-class with a comment like::
+class with a comment like:
+
+.. code-block:: cpp
 
    /**
     * @brief A class
@@ -15,7 +17,7 @@ class with a comment like::
     * \int_a^b f(x) dx = F(b) - F(a)
     * @f]
     */
-   class MathHelper 
+   class MathHelper
    {
    public:
      MathHelper() {}
@@ -34,9 +36,11 @@ Will be renderer as:
 
 
 Without any additional configuration except for including a math extension in
-the Sphinx ``conf.py``::
+the Sphinx ``conf.py``:
+
+.. code-block:: python
 
-   extensions = [ "breathe", "sphinx.ext.mathjax" ]
+   extensions = ["breathe", "sphinx.ext.mathjax"]
 
 The specific environment formula fails when using ``sphinx.ext.pngmath`` so more
 work is needed.
@@ -55,4 +59,3 @@ Credits
 Thank you to `dazzlezhang <https://github.com/dazzlezhang>`_ for providing
 examples and a full run down of necessary details.  It made the implementation
 much easier.
-
diff --git a/documentation/source/lists.rst b/documentation/source/lists.rst
index bc9fcb521..390071754 100644
--- a/documentation/source/lists.rst
+++ b/documentation/source/lists.rst
@@ -6,7 +6,9 @@ follows.
 
 .. cpp:namespace:: @ex_lists_plus
 
-For unordered lists with list items prefixed with **+** ::
+For unordered lists with list items prefixed with **+**:
+
+.. code-block:: rst
 
    .. doxygenclass:: SimpleList_1
       :project: lists
@@ -75,11 +77,12 @@ Numbered lists with list items prefixed with Arabic numerals **1. 2. ...** rende
 
 ----
 
-.. note:: Numbered lists support for the moment only Arabic numerals.
+.. note::
+   Numbered lists support for the moment only Arabic numerals.
+
 
-   
 Nested lists are supported in all combinations, as long as they are valid doxygen markup.
-Below are a couple of examples of different nested lists documentation and their corresponding 
+Below are a couple of examples of different nested lists documentation and their corresponding
 breathe output.
 
 .. cpp:namespace:: @ex_lists_nested_1
diff --git a/documentation/source/markups.rst b/documentation/source/markups.rst
index cdef1b32a..71e9e412e 100644
--- a/documentation/source/markups.rst
+++ b/documentation/source/markups.rst
@@ -16,7 +16,9 @@ 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::
+with the markup **embed:rst**. This means that a comment block like this:
+
+.. code-block:: cpp
 
    /*!
    Inserting additional reStructuredText information.
@@ -31,6 +33,7 @@ Will be rendered as:
 
 .. doxygenfunction:: TestClass::rawVerbatim
    :project: rst
+   :no-link:
 
 Handling Leading Asterisks
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -39,13 +42,17 @@ Handling Leading Asterisks
 
 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::
+such as the following:
+
+.. code-block:: cpp
 
    /*!
     * Inserting additional reStructuredText information.
     *
     * \verbatim embed:rst
-    *     Some example code::
+    *     Some example code
+    *
+    *     .. code-block:: cpp
     *
     *        int example(int x) {
     *            return x * 2;
@@ -57,7 +64,8 @@ As the leading asterisks are captured in the **verbatim** block this will
 appear to be an incorrectly formatted bullet list.  Due to the syntactical
 problems Sphinx will issue warnings and the block will render as:
 
-.. Here we fake the bad output without actually using a bad example otherwise
+..
+   Here we fake the bad output without actually using a bad example otherwise
    we'll get warnings in the build output.
 
 void **rawBadAsteriskVerbatim**\ ()
@@ -69,7 +77,9 @@ void **rawBadAsteriskVerbatim**\ ()
    - return x \* 2;
    - }
 
-To prevent this, use an **embed:rst:leading-asterisk** tag::
+To prevent this, use an **embed:rst:leading-asterisk** tag:
+
+.. code-block:: cpp
 
    /*!
     * Inserting additional reStructuredText information.
@@ -98,7 +108,9 @@ 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::
+triple forward slash. For example:
+
+.. code-block:: cpp
 
    /// Some kind of method
    ///
@@ -114,6 +126,7 @@ triple forward slash. For example::
    ///       };
    ///
    /// @endverbatim
+   /// @note Documentation using `///` should begin and end in a blank line.
 
 For these kinds of blocks, you can use an **embed:rst:leading-slashes** tag as
 shown in the above example.
@@ -134,7 +147,9 @@ Inline rST
 
 Normal verbatim elements result in block elements. But sometimes you'll want
 to generate rST references where they need to be rendered inline with the text.
-For example::
+For example:
+
+.. code-block:: cpp
 
    /// Some kind of method
    ///
@@ -165,31 +180,35 @@ Aliases
 .. cpp:namespace:: @ex_markups_aliases
 
 To make these blocks appear as more appropriate doxygen-like markup in your
-comments you can add the following aliases to your doxygen configuration file::
+comments you can add the following aliases to your doxygen configuration file:
+
+.. code-block:: text
 
    ALIASES = "rst=^^\verbatim embed:rst^^"
    ALIASES += "endrst=\endverbatim"
 
-Which allow you to write comments like::
+Which allow you to write comments like:
 
-    /*!
-    Inserting additional reStructuredText information.
+.. code-block:: cpp
 
-    \rst
+   /*!
+   Inserting additional reStructuredText information.
 
-    This is some funky non-xml compliant text: <& !><
+   \rst
 
-    .. note::
+   This is some funky non-xml compliant text: <& !><
+
+   .. note::
 
        This reStructuredText has been handled correctly.
-    \endrst
+   \endrst
 
-    This is just a standard verbatim block with code:
+   This is just a standard verbatim block with code:
 
-    \verbatim
-        child = 0;
-        while( child = parent->IterateChildren( child ) )
-    \endverbatim
+   \verbatim
+       child = 0;
+       while( child = parent->IterateChildren( child ) )
+   \endverbatim
 
     */
 
@@ -207,7 +226,9 @@ Which will be rendered as:
 
 The ALIAS given above only works for comment blocks without a leading comment character on each line.
 If you use a comment style with a leading comment character on each new line,
-use these aliases instead::
+use these aliases instead:
+
+.. code-block:: text
 
    ALIASES = "rst=^^\verbatim embed:rst:leading-asterisk^^"
    ALIASES += "endrst=\endverbatim"
@@ -219,8 +240,9 @@ Therefore, the ALIAS above works in all comment blocks with leading line comment
 
 If you want to hide reStructuredText output from Doxygen html and only include it in sphinx,
 use the Doxygen command ``\xmlonly``.
-This is an example alias that enables all RST sections in XML only::
+This is an example alias that enables all RST sections in XML only:
+
+.. code-block:: text
 
     ALIASES = "rst=^^\xmlonly<verbatim>embed:rst:leading-asterisk^^"
     ALIASES += "endrst=</verbatim>\endxmlonly"
-
diff --git a/documentation/source/members.rst b/documentation/source/members.rst
index 828eda973..2c372bc94 100644
--- a/documentation/source/members.rst
+++ b/documentation/source/members.rst
@@ -19,6 +19,7 @@ Specific Members
 .. doxygenclass:: testnamespace::NamespacedClassTest
    :path: ../../examples/specific/members/xml
    :members: functionS, anotherFunction
+   :no-link:
 
 No Members
 ----------
@@ -27,13 +28,14 @@ No Members
 
 .. doxygenclass:: testnamespace::NamespacedClassTest
    :path: ../../examples/specific/members/xml
+   :no-link:
 
 Struct Members
 ----------------
 
 .. cpp:namespace:: @ex_members_struct
 
-.. doxygenfunction:: testnamespace::MyClass::MyClass
+.. doxygenfunction:: testnamespace::MyClass::MyClass()
    :path: ../../examples/specific/struct_function/xml
 
 .. doxygenfunction:: testnamespace::MyClass::MyClass(const MyClass&)
diff --git a/documentation/source/namespace.rst b/documentation/source/namespace.rst
index 87c12c46b..e99103e8a 100644
--- a/documentation/source/namespace.rst
+++ b/documentation/source/namespace.rst
@@ -85,12 +85,13 @@ Produces this output:
 .. doxygennamespace:: foo
    :project: namespace
    :content-only:
+   :no-link:
 
 .. note::
 
    As you can see from the output, section headings like 'Functions' are missing
-   from the :content-only: display. This is due to an implementation detail. If
-   post an issue on github if you'd like it addressed.
+   from the ``:content-only:`` display. This is due to an implementation detail. Open
+   an issue on github if you'd like it addressed.
 
 
 Members Example
@@ -103,7 +104,7 @@ classes. The output for any class in the namespace should be the same as if it h
 be produced by the :ref:`doxygenclass directive <class-example>` with the
 ``members`` option specified.
 
-::
+.. code-block:: rst
 
    .. doxygennamespace:: foo
       :project: namespace
@@ -114,6 +115,7 @@ It produces this output:
 .. doxygennamespace:: foo
    :project: namespace
    :members:
+   :no-link:
 
 
 Protected Members Example
@@ -126,7 +128,7 @@ members of any classes. The output for any class in the namespace should be the
 as if it had be produced by the :ref:`doxygenclass directive <class-example>`
 with the ``protected-members`` option specified.
 
-::
+.. code-block:: rst
 
    .. doxygennamespace:: foo
       :project: namespace
@@ -137,6 +139,7 @@ It produces this output:
 .. doxygennamespace:: foo
    :project: namespace
    :protected-members:
+   :no-link:
 
 
 Private-Members Example
@@ -160,7 +163,7 @@ Produces this output:
 .. doxygennamespace:: foo
    :project: namespace
    :private-members:
-
+   :no-link:
 
 Undocumented Members Example
 ----------------------------
@@ -184,6 +187,7 @@ Produces this output:
    :project: namespace
    :private-members:
    :undoc-members:
+   :no-link:
 
 .. note::
 
@@ -213,6 +217,7 @@ It produces this output:
    :project: namespace
    :members:
    :outline:
+   :no-link:
 
 
 Nested Example
@@ -231,7 +236,7 @@ Produces this output:
 
 .. doxygennamespace:: foo::ns
    :project: namespace
-
+   :no-link:
 
 Failing Example
 ---------------
@@ -247,6 +252,7 @@ This intentionally fails:
 
 It produces the following warning message:
 
-.. warning:: doxygennamespace: Cannot find namespace “madeupnamespace” in
-             doxygen xml output for project “namespace” from directory:
-             ../../examples/specific/namespacefile/xml/
+.. warning::
+   doxygennamespace: Cannot find namespace “madeupnamespace” in
+   doxygen xml output for project “namespace” from directory:
+   ../../examples/specific/namespacefile/xml/
diff --git a/documentation/source/page.rst b/documentation/source/page.rst
index 66a3cafba..974ca4747 100644
--- a/documentation/source/page.rst
+++ b/documentation/source/page.rst
@@ -11,7 +11,7 @@ for markup in the source comments. For more information check the
 
 It takes the standard ``project`` and ``path`` options.
 
-::
+.. code-block:: rst
 
    .. doxygenpage:: <page name>
       :project: ...
@@ -56,5 +56,6 @@ This intentionally fails:
 
 It produces the following warning message:
 
-.. warning:: Cannot find file "madeuppage" in doxygen xml output for project
-             "xrefsect" from directory: ../../examples/specific/xrefsect/xml/
+.. warning::
+   Cannot find file "madeuppage" in doxygen xml output for project
+   "xrefsect" from directory: ../../examples/specific/xrefsect/xml/
diff --git a/documentation/source/quickstart.rst b/documentation/source/quickstart.rst
index 3cb0fef92..f1c7748c4 100644
--- a/documentation/source/quickstart.rst
+++ b/documentation/source/quickstart.rst
@@ -14,28 +14,39 @@ We assume the following paths:
 * doxygen xml output: :file:`/home/me/docproj/doxyxml/`
 
 The documentation path should contain a folder :file:`source` containing the
-:file:`conf.py` file. The doxygen xml output folder should contain the 
+:file:`conf.py` file. The doxygen xml output folder should contain the
 :file:`index.xml` output file generated by doxygen.
 
 The following steps are required to integrate breathe functionality:
 
-#. Add the breathe path to your conf.py by adding the following line::
+#. Add the breathe path to your conf.py by adding the following line:
 
-    sys.path.append( "/home/me/docproj/ext/breathe/" )
+   .. code-block:: python
 
-#. Add breathe as an extension the line could look like this::
+     sys.path.append("/home/me/docproj/ext/breathe/")
 
-    extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'breathe' ]
+#. Add breathe as an extension the line could look like this:
 
-#. Tell breathe about the projects::
+   .. code-block:: python
 
-    breathe_projects = { "myproject": "/home/me/docproj/doxyxml/" }
+     extensions = ['sphinx.ext.pngmath', 'sphinx.ext.todo', 'breathe' ]
 
-#. Specify a default project::
+#. Tell breathe about the projects:
 
-    breathe_default_project = "myproject"
+   .. code-block:: python
 
-Once this is done you may use the following commands::
+     breathe_projects = {"myproject": "/home/me/docproj/doxyxml/"}
+
+#. Specify a default project:
+
+   .. code-block:: python
+
+     breathe_default_project = "myproject"
+
+Once this is done you may use the following commands to include documentation for different
+constructs:
+
+.. code-block:: rst
 
   .. doxygenindex::
   .. doxygenfunction::
@@ -44,8 +55,7 @@ Once this is done you may use the following commands::
   .. doxygentypedef::
   .. doxygenclass::
 
-to include documentation for different constructs. For each of these commands the
-the following directives may be specified:
+For each of these commands the following directives may be specified:
 
 ``project``
    Specifies which project, as defined in the breathe_projects config value,
diff --git a/documentation/source/readthedocs.rst b/documentation/source/readthedocs.rst
index f673649f3..adcdc0084 100644
--- a/documentation/source/readthedocs.rst
+++ b/documentation/source/readthedocs.rst
@@ -37,7 +37,7 @@ One simple way of achieving this is to add the following code to your
 
    if read_the_docs_build:
 
-       subprocess.call('cd ../doxygen; doxygen', shell=True)
+        subprocess.call('cd ../doxygen; doxygen', shell=True)
 
 The first line uses the ``READTHEDOCS`` environment variable to determine
 whether or not we are building on the Read the Docs servers. Read the Docs
@@ -63,39 +63,37 @@ order to run ``doxygen`` on the Read the Docs server.
 
 .. code-block:: python
 
-   import subprocess, sys
+    import subprocess, sys
 
-   def run_doxygen(folder):
-       """Run the doxygen make command in the designated folder"""
+    def run_doxygen(folder):
+        """Run the doxygen make command in the designated folder"""
 
-       try:
-           retcode = subprocess.call("cd %s; make" % folder, shell=True)
-           if retcode < 0:
-               sys.stderr.write("doxygen terminated by signal %s" % (-retcode))
-       except OSError as e:
-           sys.stderr.write("doxygen execution failed: %s" % e)
+        try:
+            retcode = subprocess.call("cd %s; make" % folder, shell=True)
+            if retcode < 0:
+                sys.stderr.write("doxygen terminated by signal %s" % (-retcode))
+        except OSError as e:
+            sys.stderr.write("doxygen execution failed: %s" % e)
 
 
-   def generate_doxygen_xml(app):
-       """Run the doxygen make commands if we're on the ReadTheDocs server"""
+    def generate_doxygen_xml(app):
+        """Run the doxygen make commands if we're on the ReadTheDocs server"""
 
-       read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
+        read_the_docs_build = os.environ.get('READTHEDOCS', None) == 'True'
 
-       if read_the_docs_build:
+        if read_the_docs_build:
 
-           run_doxygen("../../examples/doxygen")
-           run_doxygen("../../examples/specific")
-           run_doxygen("../../examples/tinyxml")
+            run_doxygen("../../examples/doxygen")
+            run_doxygen("../../examples/specific")
+            run_doxygen("../../examples/tinyxml")
 
 
-   def setup(app):
+    def setup(app):
 
-       # Add hook for building doxygen xml when needed
-       app.connect("builder-inited", generate_doxygen_xml)
+        # Add hook for building doxygen xml when needed
+        app.connect("builder-inited", generate_doxygen_xml)
 
 .. _Read the Docs: https://readthedocs.org/
 .. _Github: https://github.com
 .. _Bitbucket: https://bitbucket.org
 .. _specifically for this purpose: https://docs.readthedocs.org/en/latest/faq.html#how-do-i-change-behavior-for-read-the-docs
-
-
diff --git a/documentation/source/specific.rst b/documentation/source/specific.rst
index 75559b218..f39126709 100644
--- a/documentation/source/specific.rst
+++ b/documentation/source/specific.rst
@@ -27,13 +27,13 @@ Namespaced Function Examples
 
 .. cpp:namespace:: @ex_specific_namespaced_function
 
-.. doxygenfunction:: testnamespace::NamespacedClassTest::function
+.. doxygenfunction:: TestNamespaceClasses::NamespacedClassTest::function
    :path: ../../examples/specific/class/xml
 
-.. doxygenfunction:: testnamespace::ClassTest::function
+.. doxygenfunction:: TestNamespaceClasses::ClassTest::function
    :path: ../../examples/specific/class/xml
 
-.. doxygenfunction:: testnamespace::ClassTest::anotherFunction
+.. doxygenfunction:: TestNamespaceClasses::ClassTest::anotherFunction
    :path: ../../examples/specific/class/xml
 
 .. doxygenfunction:: ClassTest::function
@@ -63,20 +63,11 @@ Extern Examples
 
 .. cpp:namespace:: @ex_specific_extern_examples
 
-.. doxygenfunction:: cache_tree_matches_traversal
+.. doxygenfunction:: cache_tree_free
    :project: c_file
-
-.. doxygenvariable:: global_cache_tree
+.. doxygenstruct:: cache_tree
    :project: c_file
-
-
-Alias Example
--------------
-
-.. cpp:namespace:: @ex_specific_alias
-
-.. doxygenfunction:: frob_foos
-   :path: ../../examples/specific/alias/xml
+   :outline:
 
 Fixed Width Font
 ----------------
@@ -241,7 +232,11 @@ C++ Inherited Members
 
 .. cpp:namespace:: @ex_specific_cpp_inherited_members
 
-.. doxygenfile:: cpp_inherited_members.h
+.. doxygenclass:: Base
+   :project: cpp_inherited_members
+.. doxygenclass:: A
+   :project: cpp_inherited_members
+.. doxygenclass:: B
    :project: cpp_inherited_members
 
 C++ Trailing Return Type
@@ -313,7 +308,7 @@ Doxygen xrefsect
 
 
 Doxygen simplesect
-----------------
+------------------
 
 .. doxygenfile:: simplesect.h
    :project: simplesect
diff --git a/documentation/source/spelling_wordlist.txt b/documentation/source/spelling_wordlist.txt
index d63d56edb..75d906eb9 100644
--- a/documentation/source/spelling_wordlist.txt
+++ b/documentation/source/spelling_wordlist.txt
@@ -38,7 +38,6 @@ conf
 inline
 License
 autodoc
-mux
 renderers
 github
 heesch
diff --git a/documentation/source/struct.rst b/documentation/source/struct.rst
index fd53f784f..9d5499c30 100644
--- a/documentation/source/struct.rst
+++ b/documentation/source/struct.rst
@@ -84,7 +84,7 @@ It produces this output:
 .. doxygenstruct:: StructTest
    :project: struct
    :members:
-
+   :no-link:
 
 Specific Members Example
 ------------------------
@@ -105,7 +105,7 @@ It produces this output:
 .. doxygenstruct:: StructTest
    :project: struct
    :members: publicFunction, protectedFunction
-
+   :no-link:
 
 Protected Members
 -----------------
@@ -126,7 +126,7 @@ It produces this output:
 .. doxygenstruct:: StructTest
    :project: struct
    :protected-members:
-
+   :no-link:
 
 Private Members
 ---------------
@@ -147,7 +147,7 @@ It produces this output:
 .. doxygenstruct:: StructTest
    :project: struct
    :private-members:
-
+   :no-link:
 
 Undocumented Members
 --------------------
@@ -174,6 +174,7 @@ It produces this output:
    :members:
    :private-members:
    :undoc-members:
+   :no-link:
 
 .. note::
 
@@ -220,7 +221,7 @@ It produces this output:
    :project: struct
    :members:
    :outline:
-
+   :no-link:
 
 Failing Example
 ---------------
@@ -237,7 +238,6 @@ This intentionally fails:
 
 It produces the following warning message:
 
-.. warning:: doxygenstruct: Cannot find struct “made_up_struct” in doxygen xml
+.. warning::
+   doxygenstruct: Cannot find struct "made_up_struct" in doxygen xml
    output for project “struct” from directory: ../../examples/doxygen/struct/xml/
-
-
diff --git a/documentation/source/tables.rst b/documentation/source/tables.rst
index 1e19dafce..a5a98650f 100644
--- a/documentation/source/tables.rst
+++ b/documentation/source/tables.rst
@@ -6,7 +6,9 @@ follows.
 
 .. cpp:namespace:: @ex_tables_simple
 
-A simple Markdown syntax table ::
+A simple Markdown syntax table:
+
+.. code-block:: rst
 
    .. doxygenclass:: Table_1
       :project: tables
@@ -22,7 +24,9 @@ It renders as:
 
 .. cpp:namespace:: @ex_tables_aligned
 
-A Markdown syntax table with alignment ::
+A Markdown syntax table with alignment:
+
+.. code-block:: rst
 
    .. doxygenclass:: Table_2
       :project: tables
@@ -38,7 +42,9 @@ It renders as:
 
 .. cpp:namespace:: @ex_tables_rowspan
 
-A Markdown syntax table with rowspan (and alignment) ::
+A Markdown syntax table with rowspan (and alignment):
+
+.. code-block:: rst
 
    .. doxygenclass:: Table_3
       :project: tables
@@ -56,7 +62,9 @@ It renders as:
 
 .. cpp:namespace:: @ex_tables_colspan
 
-A Markdown syntax table with colspan (and alignment) ::
+A Markdown syntax table with colspan (and alignment):
+
+.. code-block:: rst
 
    .. doxygenclass:: Table_4
       :project: tables
@@ -74,7 +82,9 @@ It renders as:
 
 .. cpp:namespace:: @ex_tables_doxygen
 
-A Doxygen syntax table ::
+A Doxygen syntax table:
+
+.. code-block:: rst
 
    .. doxygenclass:: Table_5
       :project: tables
diff --git a/documentation/source/template.rst b/documentation/source/template.rst
index 1cede86cb..6cf9ab8ec 100644
--- a/documentation/source/template.rst
+++ b/documentation/source/template.rst
@@ -4,7 +4,9 @@ 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::
+follows. For a class with a single template parameter:
+
+.. code-block:: rst
 
    .. doxygenclass:: templateclass
       :project: template_class
@@ -62,6 +64,3 @@ With multiple template parameters it renders as:
 
 .. doxygenfunction:: function2
    :project: template_function
-
-
-
diff --git a/documentation/source/typedef.rst b/documentation/source/typedef.rst
index f80cb1cb4..a0eb667c5 100644
--- a/documentation/source/typedef.rst
+++ b/documentation/source/typedef.rst
@@ -9,7 +9,9 @@ Working Example
 
 .. cpp:namespace:: @ex_typedef_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygentypedef:: UINT32
       :project: structcmd
@@ -24,7 +26,9 @@ Example with Namespace
 
 .. cpp:namespace:: @ex_typedef_namespace
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygentypedef:: foo::ns::MyInt
       :project: namespace
@@ -39,12 +43,14 @@ Failing Example
 
 .. cpp:namespace:: @ex_typedef_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygentypedef:: made_up_typedef
       :project: restypedef
 
 It produces the following warning message:
 
-.. warning:: doxygentypedef: Cannot find typedef "made_up_typedef" in doxygen xml output
-
+.. warning::
+   doxygentypedef: Cannot find typedef "made_up_typedef" in doxygen xml output
diff --git a/documentation/source/union.rst b/documentation/source/union.rst
index 4c993c261..638691c71 100644
--- a/documentation/source/union.rst
+++ b/documentation/source/union.rst
@@ -9,7 +9,9 @@ Working Example
 
 .. cpp:namespace:: @ex_union_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenunion:: SeparateUnion
       :project: union
@@ -24,7 +26,9 @@ Example with Namespace
 
 .. cpp:namespace:: @ex_union_namespace
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenunion:: foo::MyUnion
       :project: union
@@ -39,13 +43,15 @@ Failing Example
 
 .. cpp:namespace:: @ex_union_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenunion:: made_up_union
       :project: union
 
 It produces the following warning message:
 
-.. warning:: doxygenunion: Cannot find union "made_up_union" in doxygen XML
+.. warning::
+   doxygenunion: Cannot find union "made_up_union" in doxygen XML
    output for project "union" from directory: ../../examples/specific/union/xml/
-
diff --git a/documentation/source/variable.rst b/documentation/source/variable.rst
index adb1bc502..e9b50231f 100644
--- a/documentation/source/variable.rst
+++ b/documentation/source/variable.rst
@@ -9,7 +9,9 @@ Working Example
 
 .. cpp:namespace:: @ex_variable_example
 
-This should work::
+This should work:
+
+.. code-block:: rst
 
    .. doxygenvariable:: global_cache_tree
       :project: c_file
@@ -24,11 +26,15 @@ Failing Example
 
 .. cpp:namespace:: @ex_variable_failing
 
-This intentionally fails::
+This intentionally fails:
+
+.. code-block:: rst
 
    .. doxygenvariable:: made_up_variable
       :project: define
 
 It produces the following warning message:
 
-.. warning:: doxygenvariable: Cannot find variable “made_up_variable” in doxygen XML output for project “tinyxml” from directory: ../../examples/tinyxml/tinyxml/xml/
+.. warning::
+   doxygenvariable: Cannot find variable “made_up_variable” in doxygen XML output for project
+   "tinyxml" from directory: ../../examples/tinyxml/tinyxml/xml/
diff --git a/examples/doxygen/.gitignore b/examples/doxygen/.gitignore
index a2a25c86f..4c599a6ed 100644
--- a/examples/doxygen/.gitignore
+++ b/examples/doxygen/.gitignore
@@ -15,7 +15,6 @@ include
 jdstyle
 manual
 memgrp
-mux
 overload
 page
 par
diff --git a/examples/doxygen/Makefile b/examples/doxygen/Makefile
index 0c5a7e63f..a47970c06 100644
--- a/examples/doxygen/Makefile
+++ b/examples/doxygen/Makefile
@@ -45,7 +45,6 @@ all: class/xml/index.xml \
      memgrp/xml/index.xml \
      docstring/xml/index.xml \
      pyexample/xml/index.xml \
-     mux/xml/index.xml \
      manual/xml/index.xml \
      interface/xml/index.xml
 
@@ -53,7 +52,7 @@ clean:
 	rm -rf  class concept define enum file func page relates author \
 		par parblock overload example include qtstyle jdstyle structcmd \
 		autolink tag restypedef afterdoc template tag group diagrams \
-		memgrp docstring pyexample mux manual interface
+		memgrp docstring pyexample manual interface
 
 class/xml/index.xml: class.h class.cfg
 	$(DOXYGEN) class.cfg
@@ -132,9 +131,6 @@ memgrp/xml/index.xml: memgrp.cpp memgrp.cfg
 pyexample/xml/index.xml: pyexample.py pyexample.cfg
 	$(DOXYGEN) pyexample.cfg
 
-mux/xml/index.xml: mux.vhdl mux.cfg
-	$(DOXYGEN) mux.cfg
-
 manual/xml/index.xml: manual.c manual.cfg
 	$(DOXYGEN) manual.cfg
 
diff --git a/examples/doxygen/autolink.cpp b/examples/doxygen/autolink.cpp
index 66c238798..4c49ff2ea 100644
--- a/examples/doxygen/autolink.cpp
+++ b/examples/doxygen/autolink.cpp
@@ -12,7 +12,7 @@
 
   A link to the global enumeration type #GlobEnum.
  
-  A link to the define #ABS(x).
+  A link to the define #ABS_NUMBER(x).
   
   A link to the destructor of the Test2 class: Test2::~Test2,
   
@@ -42,7 +42,7 @@
 
   A link to the global enumeration type #GlobEnum.
   
-  A link to the define ABS(x).
+  A link to the define ABS_NUMBER(x).
   
   A link to a variable \link #var using another text\endlink as a link.
   
@@ -92,7 +92,7 @@ enum GlobEnum {
 /*!
  *  A macro definition.
  */ 
-#define ABS(x) (((x)>0)?(x):-(x))
+#define ABS_NUMBER(x) (((x)>0)?(x):-(x))
 
 typedef Test2 Test2TypeDef;
 
diff --git a/examples/doxygen/enum.h b/examples/doxygen/enum.h
index 78a64971e..1d6748d6a 100644
--- a/examples/doxygen/enum.h
+++ b/examples/doxygen/enum.h
@@ -10,6 +10,7 @@ class Test4
       V2  /*!< value 2 */
     };
 
+    /*! Another enum, with inline docs (using an explicit datatype) */
     enum class AnotherScopedEnum : long
     {
       V1, /*!< value 1 */
diff --git a/examples/doxygen/memgrp.cfg b/examples/doxygen/memgrp.cfg
index e920ca490..554ffc607 100644
--- a/examples/doxygen/memgrp.cfg
+++ b/examples/doxygen/memgrp.cfg
@@ -10,3 +10,5 @@ DISTRIBUTE_GROUP_DOC = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
\ No newline at end of file
diff --git a/examples/doxygen/memgrp.cpp b/examples/doxygen/memgrp.cpp
index 1f59b4310..052f09301 100644
--- a/examples/doxygen/memgrp.cpp
+++ b/examples/doxygen/memgrp.cpp
@@ -10,6 +10,7 @@ class Test9
 
     /** Function without group. Details. */
     void ungroupedFunction();
+    // intentionally not documenting this member?
     void func1InGroup2();
   protected:
     void func2InGroup2();
diff --git a/examples/doxygen/mux.cfg b/examples/doxygen/mux.cfg
deleted file mode 100644
index 999215090..000000000
--- a/examples/doxygen/mux.cfg
+++ /dev/null
@@ -1,15 +0,0 @@
-PROJECT_NAME         = Mux
-OUTPUT_DIRECTORY     = mux
-GENERATE_LATEX       = NO
-GENERATE_MAN         = NO
-GENERATE_RTF         = NO
-CASE_SENSE_NAMES     = NO
-INPUT                = mux.vhdl
-OPTIMIZE_OUTPUT_VHDL = YES
-QUIET                = YES
-INHERIT_DOCS         = YES
-EXTRACT_PRIVATE      = YES
-HIDE_SCOPE_NAMES     = YES
-INHERIT_DOCS         = NO
-GENERATE_HTML = NO
-GENERATE_XML = YES
diff --git a/examples/doxygen/mux.vhdl b/examples/doxygen/mux.vhdl
deleted file mode 100644
index e2c63451d..000000000
--- a/examples/doxygen/mux.vhdl
+++ /dev/null
@@ -1,32 +0,0 @@
--------------------------------------------------------
---! @file
---! @brief 2:1 Mux using with-select
--------------------------------------------------------
-
---! Use standard library
-library ieee;
---! Use logic elements
-    use ieee.std_logic_1164.all;
-
---! Mux entity brief description
-
---! Detailed description of this 
---! mux design element.
-entity mux_using_with is
-    port (
-        din_0   : in  std_logic; --! Mux first input
-        din_1   : in  std_logic; --! Mux Second input
-        sel     : in  std_logic; --! Select input
-        mux_out : out std_logic  --! Mux output
-    );
-end entity;
-
---! @brief Architecture definition of the MUX
---! @details More details about this mux element.
-architecture behavior of mux_using_with is
-begin
-    with (sel) select
-    mux_out <= din_0 when '0',
-               din_1 when others;
-end architecture;
-
diff --git a/examples/doxygen/structcmd.h b/examples/doxygen/structcmd.h
index 85044cffa..7de1b29e0 100644
--- a/examples/doxygen/structcmd.h
+++ b/examples/doxygen/structcmd.h
@@ -4,7 +4,7 @@
     Details.
 */
 
-/*! \def MAX(a,b)
+/*! \def MAX_NUMBER(a,b)
     \brief A macro that returns the maximum of \a a and \a b.
    
     Details.
@@ -50,7 +50,7 @@
     \param count The number of bytes to read.
 */
 
-#define MAX(a,b) (((a)>(b))?(a):(b))
+#define MAX_NUMBER(a,b) (((a)>(b))?(a):(b))
 typedef unsigned int UINT32;
 int errno;
 int open(const char *,int);
diff --git a/examples/doxygen/tag.cfg b/examples/doxygen/tag.cfg
index 478701ef3..2f2e5aba8 100644
--- a/examples/doxygen/tag.cfg
+++ b/examples/doxygen/tag.cfg
@@ -6,7 +6,6 @@ GENERATE_RTF     = NO
 CASE_SENSE_NAMES = NO
 INPUT            = tag.cpp
 TAGFILES         = example.tag=../../example/html
-PERL_PATH        = perl
 QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
diff --git a/examples/specific/Makefile b/examples/specific/Makefile
index 47da8e2ae..91941d5bf 100644
--- a/examples/specific/Makefile
+++ b/examples/specific/Makefile
@@ -55,7 +55,7 @@ $(xmls): %/xml/index.xml: %.cfg %.h
 programlisting/xml/index.xml: programlisting.h programlisting.cfg programlistinginclude.txt
 	$(DOXYGEN) programlisting.cfg
 
-decl_impl/xml/index.xml: decl_impl.h decl_impl.c decl_impl.cfg
+decl_impl/xml/index.xml: decl_impl.h decl_impl.cpp decl_impl.cfg
 	$(DOXYGEN) decl_impl.cfg
 
 multifilexml/xml/index.xml: multifile/one/Util.h multifile/two/Util.h multifile.cfg
diff --git a/examples/specific/alias.cfg b/examples/specific/alias.cfg
index 6abd7c30f..841abc6fd 100644
--- a/examples/specific/alias.cfg
+++ b/examples/specific/alias.cfg
@@ -9,5 +9,4 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
-ALIASES                = "sideeffect=\par Side Effects\n"
-
+ALIASES                = "sideeffect=\par Side Effects^^"
diff --git a/examples/specific/alias.h b/examples/specific/alias.h
index 8f78dfb90..33ee5bc82 100644
--- a/examples/specific/alias.h
+++ b/examples/specific/alias.h
@@ -1,17 +1,15 @@
 
-/*! @file */
+/*! @file alias.h */
 
 /**
  * Foo frob routine.
  * \par bob this something else
  * @sideeffect Frobs any foos.
- * @return Frobs any foos.
  *
  * \par bob this something else
  *
  * @sideeffect Frobs any foos.
  *
- * @param Frobs any foos.
+ * @param[out] Frobs any foos.
  */
 void frob_foos(void* Frobs);
-
diff --git a/examples/specific/array.cfg b/examples/specific/array.cfg
index 241f84dcc..3f2bebde7 100644
--- a/examples/specific/array.cfg
+++ b/examples/specific/array.cfg
@@ -9,4 +9,4 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
-
+OPTIMIZE_OUTPUT_FOR_C = YES
\ No newline at end of file
diff --git a/examples/specific/array.h b/examples/specific/array.h
index cc0f1662e..034e645de 100644
--- a/examples/specific/array.h
+++ b/examples/specific/array.h
@@ -2,6 +2,12 @@
 /** My function */
 int foo(int a[5]);
 
-/** My other function */
-int bar(int n, int a[static n]);
-
+/** My other function 
+ * 
+ * @test This declaration is supposed to be
+ * @code{.c}
+ * int bar(int n, int a[static n]);
+ * @endcode
+ * But, Sphinx fails to recognize `int a[static n])` as a C specific array syntax
+ */
+int bar(int n, int a[]);
diff --git a/examples/specific/c_file.cfg b/examples/specific/c_file.cfg
index 8833a9187..4dd2dce90 100644
--- a/examples/specific/c_file.cfg
+++ b/examples/specific/c_file.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/c_file.h b/examples/specific/c_file.h
index 76e470722..23e40f183 100644
--- a/examples/specific/c_file.h
+++ b/examples/specific/c_file.h
@@ -26,7 +26,7 @@ struct cache_tree {
 extern struct cache_tree global_cache_tree;
 
 struct cache_tree *cache_tree(void);
-void cache_tree_free(struct cache_tree **);
+extern void cache_tree_free(struct cache_tree **);
 void cache_tree_invalidate_path(struct cache_tree *, const char *);
 struct cache_tree_sub *cache_tree_sub(struct cache_tree *, const char *);
 
@@ -51,4 +51,3 @@ void prime_cache_tree(struct cache_tree **, struct tree *);
 extern int cache_tree_matches_traversal(struct cache_tree *, struct name_entry *ent, struct traverse_info *info);
 
 #endif
-
diff --git a/examples/specific/c_struct.cfg b/examples/specific/c_struct.cfg
index 195033631..3ebfc1953 100644
--- a/examples/specific/c_struct.cfg
+++ b/examples/specific/c_struct.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/c_union.cfg b/examples/specific/c_union.cfg
index 46e54d45a..517b79710 100644
--- a/examples/specific/c_union.cfg
+++ b/examples/specific/c_union.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/class.cfg b/examples/specific/class.cfg
index 6a11d7e2e..61208d14a 100644
--- a/examples/specific/class.cfg
+++ b/examples/specific/class.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/class.h b/examples/specific/class.h
index 9bb371b43..3301c0001 100644
--- a/examples/specific/class.h
+++ b/examples/specific/class.h
@@ -1,5 +1,6 @@
+#include <string>
 
-namespace testnamespace {
+namespace TestNamespaceClasses {
 
 //! \brief first class inside of namespace
 class NamespacedClassTest {
@@ -32,7 +33,7 @@ class ClassTest {
 };
 
 
-}
+} // TestNamespaceClasses
 
 //! \brief class outside of namespace
 class OuterClass {
@@ -94,9 +95,9 @@ class ClassTest {
 private:
 
     //! This is a private function
-    void privateFunction() const = 0;
+    virtual void privateFunction() const = 0;
 
-    void undocumentedPrivateFunction() const = 0;
+    virtual void undocumentedPrivateFunction() const = 0;
 
     //! A private class
     class PrivateClass {};
diff --git a/examples/specific/cpp_anon.cfg b/examples/specific/cpp_anon.cfg
index 34d071ab7..7becf1974 100644
--- a/examples/specific/cpp_anon.cfg
+++ b/examples/specific/cpp_anon.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/cpp_friendclass.cfg b/examples/specific/cpp_friendclass.cfg
index fe545337d..b34b493cc 100644
--- a/examples/specific/cpp_friendclass.cfg
+++ b/examples/specific/cpp_friendclass.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/cpp_function.cfg b/examples/specific/cpp_function.cfg
index 43033c1d7..31f6290d6 100644
--- a/examples/specific/cpp_function.cfg
+++ b/examples/specific/cpp_function.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/cpp_function.h b/examples/specific/cpp_function.h
index 59af74f69..a09c92e46 100644
--- a/examples/specific/cpp_function.h
+++ b/examples/specific/cpp_function.h
@@ -1,3 +1,4 @@
+struct Foo{};
 struct Class {
 	virtual void f1() const volatile & = 0;
 	virtual void f2() const volatile && = 0;
@@ -8,3 +9,9 @@ struct Class {
 
 	int f_issue_338() noexcept;
 };
+
+/** A namespace to demonstrate a namespaced function */
+namespace TestNamespaceFunction {
+/** A function within a namspace. */
+void namespaceFunc();
+}
diff --git a/examples/specific/cpp_trailing_return_type.h b/examples/specific/cpp_trailing_return_type.h
index 25235384f..8954b2df0 100644
--- a/examples/specific/cpp_trailing_return_type.h
+++ b/examples/specific/cpp_trailing_return_type.h
@@ -1,4 +1,7 @@
-class Thingy;
+/*! \file cpp_trailing_return_type.h */
+
+/*! needed for references in global function return type */
+class Thingy {};
 
 //! \brief Function that creates a thingy.
 auto f_issue_441() -> Thingy*;
diff --git a/examples/specific/cpp_union.cfg b/examples/specific/cpp_union.cfg
index f4324b884..03000d872 100644
--- a/examples/specific/cpp_union.cfg
+++ b/examples/specific/cpp_union.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/decl_impl.cfg b/examples/specific/decl_impl.cfg
index 5e5db76a0..0001f9941 100644
--- a/examples/specific/decl_impl.cfg
+++ b/examples/specific/decl_impl.cfg
@@ -4,7 +4,7 @@ GENERATE_LATEX   = NO
 GENERATE_MAN     = NO
 GENERATE_RTF     = NO
 CASE_SENSE_NAMES = NO
-INPUT            = decl_impl.h decl_impl.c
+INPUT            = decl_impl.h decl_impl.cpp
 QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
diff --git a/examples/specific/decl_impl.c b/examples/specific/decl_impl.cpp
similarity index 79%
rename from examples/specific/decl_impl.c
rename to examples/specific/decl_impl.cpp
index a32813cec..e2272f0e3 100644
--- a/examples/specific/decl_impl.c
+++ b/examples/specific/decl_impl.cpp
@@ -2,7 +2,7 @@
 
     Yeah and some more.
 */
-int open_di(const char * a, int b) {
+int open_di(const char * pathname, int flags) {
 	return 0;
 }
 
@@ -15,4 +15,3 @@ int another_open_di(const char *,int)
 }
 
 }
-
diff --git a/examples/specific/define.h b/examples/specific/define.h
index addaf0cd9..c5bc29805 100644
--- a/examples/specific/define.h
+++ b/examples/specific/define.h
@@ -18,7 +18,7 @@
  *
  * \returns The maximum of A and B
  */
-#define MAX(A,B) ((A > B)?(A):(B))
+#define MAXIMUM(A,B) ((A > B)?(A):(B))
 
 
 /**
diff --git a/examples/specific/dot_graphs.cfg b/examples/specific/dot_graphs.cfg
index 62b226e95..02646377c 100644
--- a/examples/specific/dot_graphs.cfg
+++ b/examples/specific/dot_graphs.cfg
@@ -11,3 +11,4 @@ QUIET             = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML     = NO
 GENERATE_XML      = YES
+WARNINGS          = NO
diff --git a/examples/specific/enum.h b/examples/specific/enum.h
index 14aa3382a..0eeb72847 100644
--- a/examples/specific/enum.h
+++ b/examples/specific/enum.h
@@ -1,5 +1,5 @@
 
-namespace testnamespace {
+namespace TestEnumNamespace {
 
 //! \brief enum inside of namespace
 enum NamespacedEnumTest {
diff --git a/examples/specific/fixedwidthfont.cfg b/examples/specific/fixedwidthfont.cfg
index bace9fcaf..afdd2717e 100644
--- a/examples/specific/fixedwidthfont.cfg
+++ b/examples/specific/fixedwidthfont.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/functionOverload.h b/examples/specific/functionOverload.h
index 5ce4b4cf9..d6550e6f8 100644
--- a/examples/specific/functionOverload.h
+++ b/examples/specific/functionOverload.h
@@ -1,3 +1,4 @@
+#include <string>
 
 //! Non overloaded function
 void simplefunc();
@@ -18,8 +19,10 @@ void g(double, double);
 
 }
 
+/*! needed for references in global function parameters */
 class MyType {};
 
+/*! needed for references in global function parameters */
 class MyOtherType {};
 
 //! Another function which takes a custom type
diff --git a/examples/specific/group.cfg b/examples/specific/group.cfg
index b187a1473..807717933 100644
--- a/examples/specific/group.cfg
+++ b/examples/specific/group.cfg
@@ -11,3 +11,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/group.h b/examples/specific/group.h
index 2135cb1da..e5d7589b4 100644
--- a/examples/specific/group.h
+++ b/examples/specific/group.h
@@ -33,9 +33,9 @@ class GroupedClassTest {
 private:
 
     //! This is a private function
-    void privateFunction() const = 0;
+    virtual void privateFunction() const = 0;
 
-    void undocumentedPrivateFunction() const = 0;
+    virtual void undocumentedPrivateFunction() const = 0;
 
     //! A private class
     class PrivateClass {};
@@ -88,4 +88,3 @@ class UngroupedClassTest {
 
 //! Ungrouped function
 void ungroupedFunction();
-
diff --git a/examples/specific/headings.h b/examples/specific/headings.h
index 0b441cb59..0cb8e5817 100644
--- a/examples/specific/headings.h
+++ b/examples/specific/headings.h
@@ -15,5 +15,4 @@ Text
 ### Header ###
 Text
 */
-class Test {};
-
+class HeadingsTest {};
diff --git a/examples/specific/image.h b/examples/specific/image.h
index 94bae494b..015a97f3b 100644
--- a/examples/specific/image.h
+++ b/examples/specific/image.h
@@ -6,6 +6,4 @@
 * Breathe & Sphinx should automatically copy the image from the doxygen output directory into the
 * _images folder of the Sphinx output.
 */
-class ImageClass : public Image {}
-
-
+class ImageClass {};
diff --git a/examples/specific/inline.h b/examples/specific/inline.h
index 7aeea8c97..a21313c3d 100644
--- a/examples/specific/inline.h
+++ b/examples/specific/inline.h
@@ -1,5 +1,6 @@
-
-class Test
+#include <stdexcept>
+/** A class to demonstrate inline documentation syntax. */
+class InlineTest
 {
  public:
  /** A member function.
@@ -14,4 +15,3 @@ class Test
 
  throw(std::out_of_range);
 };
-
diff --git a/examples/specific/links.h b/examples/specific/links.h
index efbed7f06..ef09f6949 100644
--- a/examples/specific/links.h
+++ b/examples/specific/links.h
@@ -6,7 +6,4 @@
   handling of links.
 
  */
-class Test {};
-
-
-
+class LinksTest {};
diff --git a/examples/specific/multifile.cfg b/examples/specific/multifile.cfg
index e41e73264..566969b3b 100644
--- a/examples/specific/multifile.cfg
+++ b/examples/specific/multifile.cfg
@@ -10,3 +10,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/namespacefile.cfg b/examples/specific/namespacefile.cfg
index 072e3609c..a43071e16 100644
--- a/examples/specific/namespacefile.cfg
+++ b/examples/specific/namespacefile.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/namespacefile.h b/examples/specific/namespacefile.h
index 078448045..36c8ab947 100644
--- a/examples/specific/namespacefile.h
+++ b/examples/specific/namespacefile.h
@@ -30,9 +30,9 @@ namespace foo {
     private:
 
         //! This is a private function
-        void privateFunction() const = 0;
+        virtual void privateFunction() const = 0;
 
-        void undocumentedPrivateFunction() const = 0;
+        virtual void undocumentedPrivateFunction() const = 0;
 
         //! A private class
         class PrivateClass {};
@@ -76,4 +76,3 @@ class OuterBar {
 
 /** Function outside of the namespace */
 void outerFunction() {};
-
diff --git a/examples/specific/qtsignalsandslots.cfg b/examples/specific/qtsignalsandslots.cfg
index 464dace23..2d976b816 100644
--- a/examples/specific/qtsignalsandslots.cfg
+++ b/examples/specific/qtsignalsandslots.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/qtsignalsandslots.h b/examples/specific/qtsignalsandslots.h
index af750f0e7..493e1708e 100644
--- a/examples/specific/qtsignalsandslots.h
+++ b/examples/specific/qtsignalsandslots.h
@@ -1,7 +1,12 @@
 #ifndef QT_OBJECT_H
 #define QT_OBJECT_H
 
-#include
+/*!
+*\brief Forward declaration of QT API class
+
+QT slots and signals typically `#include <QObject>`, but this example is parsed without QT SDK installed.
+*/
+extern class QObject;
 
 class QtSignalSlotExample: public QObject
 {
@@ -18,7 +23,7 @@ class QtSignalSlotExample: public QObject
     signals:
 
     /*!
-     *\param iShown
+     \param iShown
      This is in function declaration
      */
     void workingSignal( int iShown );
@@ -26,7 +31,7 @@ class QtSignalSlotExample: public QObject
     public slots:
 
     /*!
-     *\param iShown
+     \param iShown
      This is in function declaration
      */
     void workingSlot( int iShown ) { iShown; }
diff --git a/examples/specific/rst.h b/examples/specific/rst.h
index 7c9a54b16..24d88b310 100644
--- a/examples/specific/rst.h
+++ b/examples/specific/rst.h
@@ -49,11 +49,9 @@ class TestClass
     */
     virtual void rawLeadingAsteriskVerbatim() const = 0;
 
-    //////////////////////////////////////////////////////////////
     /// Some kind of method
     ///
     /// @param something a parameter
-    /// @returns the same value provided in something param
     ///
     /// @verbatim embed:rst:leading-slashes
     ///    .. code-block:: c
@@ -64,7 +62,8 @@ class TestClass
     ///       };
     ///
     /// @endverbatim
-    //////////////////////////////////////////////////////////////
+    /// @note Documentation using `///` should begin and end in a blank line.
+
     virtual void rawLeadingSlashesVerbatim(int something) const = 0;
 
     /*!
diff --git a/examples/specific/struct.cfg b/examples/specific/struct.cfg
index 12ba11cb1..538d5a966 100644
--- a/examples/specific/struct.cfg
+++ b/examples/specific/struct.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/struct.h b/examples/specific/struct.h
index 0b3b92777..78440d50b 100644
--- a/examples/specific/struct.h
+++ b/examples/specific/struct.h
@@ -64,14 +64,12 @@ struct StructTest {
 private:
 
     //! This is a private function
-    void privateFunction() const = 0;
+    virtual void privateFunction() const = 0;
 
-    void undocumentedPrivateFunction() const = 0;
+    virtual void undocumentedPrivateFunction() const = 0;
 
     //! A private class
     class PrivateClass {};
 
     class UndocumentedPrivateClass {};
 };
-
-
diff --git a/examples/specific/struct_function.cfg b/examples/specific/struct_function.cfg
index 30f96bed0..2f1b38506 100644
--- a/examples/specific/struct_function.cfg
+++ b/examples/specific/struct_function.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/typedef.cfg b/examples/specific/typedef.cfg
index a070035b3..57c548ca8 100644
--- a/examples/specific/typedef.cfg
+++ b/examples/specific/typedef.cfg
@@ -9,3 +9,5 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/typedef.h b/examples/specific/typedef.h
index 8a11a70d4..712688c7b 100644
--- a/examples/specific/typedef.h
+++ b/examples/specific/typedef.h
@@ -15,7 +15,7 @@ typedef float floatingPointNumber;
 
 typedef int TestTypedef;
 
-namespace testnamespace {
+namespace TypeDefNamespace {
   typedef char *AnotherTypedef;
 }
 
diff --git a/examples/specific/union.h b/examples/specific/union.h
index 39ba24932..a8e4b7635 100644
--- a/examples/specific/union.h
+++ b/examples/specific/union.h
@@ -34,6 +34,5 @@ class ClassWithUnion
     {
         int a_member;
         float another_member;
-    }
+    };
 };
-
diff --git a/examples/specific/userdefined.cfg b/examples/specific/userdefined.cfg
index c081568fd..00a16e7de 100644
--- a/examples/specific/userdefined.cfg
+++ b/examples/specific/userdefined.cfg
@@ -11,3 +11,4 @@ GENERATE_HTML = NO
 GENERATE_XML = YES
 DISTRIBUTE_GROUP_DOC = YES
 
+WARN_IF_UNDOCUMENTED = NO
diff --git a/examples/specific/userdefined.h b/examples/specific/userdefined.h
index 87d1dfdea..7bb8827ba 100644
--- a/examples/specific/userdefined.h
+++ b/examples/specific/userdefined.h
@@ -1,7 +1,7 @@
 // Example from Doxygen documentation
 
-/** A class. More details about the Test class */
-class Test
+/** A class. More details about the UserDefinedGroupTest class */
+class UserDefinedGroupTest
 {
   public:
     //@{
@@ -17,17 +17,15 @@ class Test
     void func2InCustomGroup();
 };
 
-void Test::func1InGroup1() {}
-void Test::func2InGroup1() {}
+void UserDefinedGroupTest::func1InGroup1() {}
+void UserDefinedGroupTest::func2InGroup1() {}
 
 /** @name Custom Group
  *  Description of custom group
  */
 //@{
 /** Function 2 in custom group. Details. */
-void Test::func2InCustomGroup() {}
+void UserDefinedGroupTest::func2InCustomGroup() {}
 /** Function 1 in custom group. Details. */
-void Test::func1InCustomGroup() {}
+void UserDefinedGroupTest::func1InCustomGroup() {}
 //@}
-
-
diff --git a/examples/tinyxml/tinyxml.cfg b/examples/tinyxml/tinyxml.cfg
index db06329ed..facfe8697 100644
--- a/examples/tinyxml/tinyxml.cfg
+++ b/examples/tinyxml/tinyxml.cfg
@@ -9,3 +9,8 @@ QUIET            = YES
 JAVADOC_AUTOBRIEF = YES
 GENERATE_HTML = NO
 GENERATE_XML = YES
+
+# tinyxml.h is huge! Ignore any problems since the project is not maintained (moved to TinyXML-2 project).
+WARN_IF_UNDOCUMENTED = NO
+WARN_IF_INCOMPLETE_DOC = NO
+WARN_IF_DOC_ERROR =  NO
\ No newline at end of file


Test patch:
diff --git a/documentation/source/testpages.rst b/documentation/source/testpages.rst
index 41576785d..7ef8f8025 100644
--- a/documentation/source/testpages.rst
+++ b/documentation/source/testpages.rst
@@ -11,5 +11,3 @@ Test Pages
    embeddedrst
    inline 
    members
-   examples/codeblocks
-
diff --git a/examples/doxygen/example_test.cpp b/examples/doxygen/example_test.cpp
index 65a158a39..581bc4af2 100644
--- a/examples/doxygen/example_test.cpp
+++ b/examples/doxygen/example_test.cpp
@@ -1,5 +1,5 @@
 void main()
 {
-  Test5 t;
+  Test7 t;
   t.example();
 }