Browse Source

documentation overhaul (#816)

* Fix all warnings in docs build

By adjusting either the restructured text or code/doxygen setup as
needed.

Including some renaming of C/C++ symbols for uniqueness so that we don't
have duplicate IDs throughout the docs.

Other parts use no-link to avoid generating unused or duplicate IDs.

Some other parts are commented out in the restructured text so that we
don't render them any more. For example, the mux vdhl stuff in the
doxygen test suite.

We've include the lists of warnings that doxygen generates but we can
get rid of those at some point.

* Pin docs CI (& RTD) to use doxygen 1.9.3

- tell sphinx to treat warnings as errors (replacing nit-picky mode)
- fix awkward word choice in a a doc
- RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable
- document the entire namespace instead individual members of the typeedf example test
- use a different member as the `extern` member test (for reason related to undefined types in member's parameters)
- define empty structures to use as a reference for a type in a parameter/return value of a documented function
   - add comments to explain what the empty structures are for
- remove unnecessary inheritence from "image" example test

* Upload xml artifacts with built docs

* Adjust restructured text usage & formatting

We use explicitly language-typed code blocks much more than before to
have better syntax highlighting.

We use links where possible instead of plain text references to
directives and config variables.

We reformat re-indent some of the text blocks as needed.

* Fix link

And further formatting tweaks.

* Remove comments with undocumented entries

We don't need a record of them.

* Completely remove mux/vhdl examples

If we're not supporting it (and we probably shouldn't) then there is no
need to keep it around in the repository.

* Remove duplicate specific examples

If there appear elsewhere in the docs then that is all that matters. We
don't need to keep commented out content about them.

* Revert some `:` changes

Also removed some trailing whitespace.

Force Doxyfile snippets to be un-highlighted by pygments (which tends to
assume its python syntax).

* missed a colon in index.rst

Co-authored-by: Michael Jones <m.pricejones@gmail.com>

* Add ':' to union.rst file

* temporarily keep RTD pinned to doxygen 1.9.2

This is done because of a problem with `\dotfile` in doxygen 1.9.3

* make dotfile test compatible with doxygen 1.9.3

If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML.

Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior.

TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag.

* suppress doxygen warnings for dotfile test

I'm painfully aware

* pin CI workflow & RTD to use doxygen v1.9.3

* use env var directly (not from CI runner context)

* Fix all warnings in docs build

By adjusting either the restructured text or code/doxygen setup as
needed.

Including some renaming of C/C++ symbols for uniqueness so that we don't
have duplicate IDs throughout the docs.

Other parts use no-link to avoid generating unused or duplicate IDs.

Some other parts are commented out in the restructured text so that we
don't render them any more. For example, the mux vdhl stuff in the
doxygen test suite.

We've include the lists of warnings that doxygen generates but we can
get rid of those at some point.

* Pin docs CI (& RTD) to use doxygen 1.9.3

- tell sphinx to treat warnings as errors (replacing nit-picky mode)
- fix awkward word choice in a a doc
- RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable
- document the entire namespace instead individual members of the typeedf example test
- use a different member as the `extern` member test (for reason related to undefined types in member's parameters)
- define empty structures to use as a reference for a type in a parameter/return value of a documented function
   - add comments to explain what the empty structures are for
- remove unnecessary inheritence from "image" example test

* Upload xml artifacts with built docs

* Adjust restructured text usage & formatting

We use explicitly language-typed code blocks much more than before to
have better syntax highlighting.

We use links where possible instead of plain text references to
directives and config variables.

We reformat re-indent some of the text blocks as needed.

* Fix link

And further formatting tweaks.

* Remove comments with undocumented entries

We don't need a record of them.

* Completely remove mux/vhdl examples

If we're not supporting it (and we probably shouldn't) then there is no
need to keep it around in the repository.

* Remove duplicate specific examples

If there appear elsewhere in the docs then that is all that matters. We
don't need to keep commented out content about them.

* Revert some `:` changes

Also removed some trailing whitespace.

Force Doxyfile snippets to be un-highlighted by pygments (which tends to
assume its python syntax).

* missed a colon in index.rst

Co-authored-by: Michael Jones <m.pricejones@gmail.com>

* Add ':' to union.rst file

* temporarily keep RTD pinned to doxygen 1.9.2

This is done because of a problem with `\dotfile` in doxygen 1.9.3

* make dotfile test compatible with doxygen 1.9.3

If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML.

Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior.

TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag.

* suppress doxygen warnings for dotfile test

I'm painfully aware

* pin CI workflow & RTD to use doxygen v1.9.3

* use env var directly (not from CI runner context)

* allow docs to use older doxygen

Specifically for building breathe's docs.

This is made possible by using the RST `ifconfig` directive.

See #811

* ran black on conf.py

* simple review changes

* reverting NS directive changes

Per request, most of the namespaced member changes are reverted.

Also reverted temporary changes to dot_graphs.cfg project as the fix was merged into master (which this branch should now be based on).

Some changes seemed to have been lost since I did a
`git reset --hard origin/branch-name`
I have restored what I noticed, but there may be some other changes that were lost.

* revert another namespace related change

reverted another namespace change in domains.rst

* remove documented return values for void functions

* revert other changes related to `-n` warnings

* revert moving `f0` funcs in specific test sections

* update mathjax_path to latest

mathjax output was currently broken due to changes in mathjax distribution path/URL. Updating to latest restores proper output.

* revert C array as requested (& hope for the best)

Maybe the error about the `.. c:function::` signature is specific to my setup.

* improve version check for doxygen & C++ concepts

* Fix all warnings in docs build

By adjusting either the restructured text or code/doxygen setup as
needed.

Including some renaming of C/C++ symbols for uniqueness so that we don't
have duplicate IDs throughout the docs.

Other parts use no-link to avoid generating unused or duplicate IDs.

Some other parts are commented out in the restructured text so that we
don't render them any more. For example, the mux vdhl stuff in the
doxygen test suite.

We've include the lists of warnings that doxygen generates but we can
get rid of those at some point.

* Pin docs CI (& RTD) to use doxygen 1.9.3

- tell sphinx to treat warnings as errors (replacing nit-picky mode)
- fix awkward word choice in a a doc
- RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable
- document the entire namespace instead individual members of the typeedf example test
- use a different member as the `extern` member test (for reason related to undefined types in member's parameters)
- define empty structures to use as a reference for a type in a parameter/return value of a documented function
   - add comments to explain what the empty structures are for
- remove unnecessary inheritence from "image" example test

* Upload xml artifacts with built docs

* Adjust restructured text usage & formatting

We use explicitly language-typed code blocks much more than before to
have better syntax highlighting.

We use links where possible instead of plain text references to
directives and config variables.

We reformat re-indent some of the text blocks as needed.

* Fix link

And further formatting tweaks.

* Remove comments with undocumented entries

We don't need a record of them.

* Completely remove mux/vhdl examples

If we're not supporting it (and we probably shouldn't) then there is no
need to keep it around in the repository.

* Remove duplicate specific examples

If there appear elsewhere in the docs then that is all that matters. We
don't need to keep commented out content about them.

* Revert some `:` changes

Also removed some trailing whitespace.

Force Doxyfile snippets to be un-highlighted by pygments (which tends to
assume its python syntax).

* missed a colon in index.rst

Co-authored-by: Michael Jones <m.pricejones@gmail.com>

* Add ':' to union.rst file

* temporarily keep RTD pinned to doxygen 1.9.2

This is done because of a problem with `\dotfile` in doxygen 1.9.3

* make dotfile test compatible with doxygen 1.9.3

If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML.

Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior.

TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag.

* suppress doxygen warnings for dotfile test

I'm painfully aware

* pin CI workflow & RTD to use doxygen v1.9.3

* use env var directly (not from CI runner context)

* Fix all warnings in docs build

By adjusting either the restructured text or code/doxygen setup as
needed.

Including some renaming of C/C++ symbols for uniqueness so that we don't
have duplicate IDs throughout the docs.

Other parts use no-link to avoid generating unused or duplicate IDs.

Some other parts are commented out in the restructured text so that we
don't render them any more. For example, the mux vdhl stuff in the
doxygen test suite.

We've include the lists of warnings that doxygen generates but we can
get rid of those at some point.

* Pin docs CI (& RTD) to use doxygen 1.9.3

- tell sphinx to treat warnings as errors (replacing nit-picky mode)
- fix awkward word choice in a a doc
- RTD will use conda forge to get updated docygen executable. GH CI will get doxygen from SourceForge archives binary executable
- document the entire namespace instead individual members of the typeedf example test
- use a different member as the `extern` member test (for reason related to undefined types in member's parameters)
- define empty structures to use as a reference for a type in a parameter/return value of a documented function
   - add comments to explain what the empty structures are for
- remove unnecessary inheritence from "image" example test

* Adjust restructured text usage & formatting

We use explicitly language-typed code blocks much more than before to
have better syntax highlighting.

We use links where possible instead of plain text references to
directives and config variables.

We reformat re-indent some of the text blocks as needed.

* Completely remove mux/vhdl examples

If we're not supporting it (and we probably shouldn't) then there is no
need to keep it around in the repository.

* Revert some `:` changes

Also removed some trailing whitespace.

Force Doxyfile snippets to be un-highlighted by pygments (which tends to
assume its python syntax).

* temporarily keep RTD pinned to doxygen 1.9.2

This is done because of a problem with `\dotfile` in doxygen 1.9.3

* make dotfile test compatible with doxygen 1.9.3

If DOTFILE_DIRS tag is specified, then doxygen 1.9.3 will copy the dot file into the XML output folder and use a relative path when specifying the dotfile's name in XML.

Breathe expects the dotfile to be specified using a absolute path (and filename) as that was the default behavior in 1.9.2 or prior.

TL;DR: don't specify the DOTFILE_DIRS tag in the doxyfile config! Currently, there is no plan to workaround using DOTFILE_DIRS tag.

* pin CI workflow & RTD to use doxygen v1.9.3

* allow docs to use older doxygen

Specifically for building breathe's docs.

This is made possible by using the RST `ifconfig` directive.

See #811

* ran black on conf.py

* simple review changes

* reverting NS directive changes

Per request, most of the namespaced member changes are reverted.

Also reverted temporary changes to dot_graphs.cfg project as the fix was merged into master (which this branch should now be based on).

Some changes seemed to have been lost since I did a
`git reset --hard origin/branch-name`
I have restored what I noticed, but there may be some other changes that were lost.

* revert another namespace related change

reverted another namespace change in domains.rst

* remove documented return values for void functions

* revert other changes related to `-n` warnings

* revert moving `f0` funcs in specific test sections

* update mathjax_path to latest

mathjax output was currently broken due to changes in mathjax distribution path/URL. Updating to latest restores proper output.

* revert C array as requested (& hope for the best)

Maybe the error about the `.. c:function::` signature is specific to my setup.

* improve version check for doxygen & C++ concepts

* ignore edge case

* let RTD use the latest doxygen

* final self-review

* found a silent error in the doxygen test pg

Co-authored-by: Michael Jones <m.pricejones@gmail.com>
pull/820/head
Brendan 2 months ago committed by GitHub
parent
commit
caba061910
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
  1. 23
      .github/workflows/documentation.yml
  2. 3
      .readthedocs.yaml
  3. 5
      documentation/Makefile
  4. 11
      documentation/environment.yaml
  5. 5
      documentation/source/_static/breathe.css
  6. 12
      documentation/source/autofile.rst
  7. 13
      documentation/source/autoindex.rst
  8. 33
      documentation/source/class.rst
  9. 12
      documentation/source/code/groups.h
  10. 9
      documentation/source/codeguide.rst
  11. 28
      documentation/source/concept.rst
  12. 18
      documentation/source/conf.py
  13. 3
      documentation/source/credits.rst
  14. 13
      documentation/source/customcss.rst
  15. 14
      documentation/source/define.rst
  16. 149
      documentation/source/directives.rst
  17. 114
      documentation/source/domains.rst
  18. 7
      documentation/source/doxygen.rst
  19. 16
      documentation/source/enum.rst
  20. 16
      documentation/source/enumvalue.rst
  21. 21
      documentation/source/examples/codeblocks.rst
  22. 28
      documentation/source/file.rst
  23. 16
      documentation/source/function.rst
  24. 26
      documentation/source/group.rst
  25. 10
      documentation/source/groups.rst
  26. 29
      documentation/source/index.rst
  27. 13
      documentation/source/latexmath.rst
  28. 11
      documentation/source/lists.rst
  29. 68
      documentation/source/markups.rst
  30. 4
      documentation/source/members.rst
  31. 24
      documentation/source/namespace.rst
  32. 7
      documentation/source/page.rst
  33. 34
      documentation/source/quickstart.rst
  34. 42
      documentation/source/readthedocs.rst
  35. 29
      documentation/source/specific.rst
  36. 1
      documentation/source/spelling_wordlist.txt
  37. 16
      documentation/source/struct.rst
  38. 20
      documentation/source/tables.rst
  39. 7
      documentation/source/template.rst
  40. 2
      documentation/source/testpages.rst
  41. 16
      documentation/source/typedef.rst
  42. 16
      documentation/source/union.rst
  43. 12
      documentation/source/variable.rst
  44. 1
      examples/doxygen/.gitignore
  45. 6
      examples/doxygen/Makefile
  46. 6
      examples/doxygen/autolink.cpp
  47. 1
      examples/doxygen/enum.h
  48. 2
      examples/doxygen/example_test.cpp
  49. 2
      examples/doxygen/memgrp.cfg
  50. 1
      examples/doxygen/memgrp.cpp
  51. 15
      examples/doxygen/mux.cfg
  52. 32
      examples/doxygen/mux.vhdl
  53. 4
      examples/doxygen/structcmd.h
  54. 1
      examples/doxygen/tag.cfg
  55. 2
      examples/specific/Makefile
  56. 3
      examples/specific/alias.cfg
  57. 6
      examples/specific/alias.h
  58. 2
      examples/specific/array.cfg
  59. 12
      examples/specific/array.h
  60. 2
      examples/specific/c_file.cfg
  61. 3
      examples/specific/c_file.h
  62. 2
      examples/specific/c_struct.cfg
  63. 2
      examples/specific/c_union.cfg
  64. 2
      examples/specific/class.cfg
  65. 9
      examples/specific/class.h
  66. 2
      examples/specific/cpp_anon.cfg
  67. 2
      examples/specific/cpp_friendclass.cfg
  68. 2
      examples/specific/cpp_function.cfg
  69. 7
      examples/specific/cpp_function.h
  70. 5
      examples/specific/cpp_trailing_return_type.h
  71. 2
      examples/specific/cpp_union.cfg
  72. 2
      examples/specific/decl_impl.cfg
  73. 3
      examples/specific/decl_impl.cpp
  74. 2
      examples/specific/define.h
  75. 1
      examples/specific/dot_graphs.cfg
  76. 2
      examples/specific/enum.h
  77. 2
      examples/specific/fixedwidthfont.cfg
  78. 3
      examples/specific/functionOverload.h
  79. 2
      examples/specific/group.cfg
  80. 5
      examples/specific/group.h
  81. 3
      examples/specific/headings.h
  82. 4
      examples/specific/image.h
  83. 6
      examples/specific/inline.h
  84. 5
      examples/specific/links.h
  85. 2
      examples/specific/multifile.cfg
  86. 2
      examples/specific/namespacefile.cfg
  87. 5
      examples/specific/namespacefile.h
  88. 2
      examples/specific/qtsignalsandslots.cfg
  89. 11
      examples/specific/qtsignalsandslots.h
  90. 5
      examples/specific/rst.h
  91. 2
      examples/specific/struct.cfg
  92. 6
      examples/specific/struct.h
  93. 2
      examples/specific/struct_function.cfg
  94. 2
      examples/specific/typedef.cfg
  95. 2
      examples/specific/typedef.h
  96. 3
      examples/specific/union.h
  97. 1
      examples/specific/userdefined.cfg
  98. 14
      examples/specific/userdefined.h
  99. 5
      examples/tinyxml/tinyxml.cfg

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

3
.readthedocs.yaml

@ -11,3 +11,6 @@ sphinx:
builder: html
configuration: documentation/source/conf.py
fail_on_warning: false
conda:
environment: documentation/environment.yaml

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

11
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

5
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;
}

12
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:

13
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

33
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/

12
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() {}
//@}

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

28
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

18
documentation/source/conf.py

@ -34,6 +34,19 @@ extensions = ["breathe", "sphinx.ext.mathjax", "sphinx.ext.ifconfig", "sphinx.ex
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 @@ spelling_lang = "en_US"
# 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")

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

13
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;
}

14
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

149
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

114
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`.

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

16
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

16
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

21
documentation/source/examples/codeblocks.rst

@ -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:

28
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/

16
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: