Add verbatim inline documentation and examples

* Update rst.h example with a function that includes an inline rST cpp domain link to another function using a verbatim * Update markups.rst with an inline verbatim section * Add Doxygen ALIAS to for an inline verbatim element Signed-off-by: Fabio Utzig <[email protected]>
breathe-doc · Sep 4, 2020 · d3f9e12 · d3f9e12
1 parent ffd5886
commit d3f9e12
Show file tree

Hide file tree

Showing 4 changed files with 41 additions and 1 deletion.
diff --git a/breathe/process.py b/breathe/process.py
@@ -26,6 +26,7 @@
 GENERATE_XML = YES
 ALIASES = "rst=\verbatim embed:rst"
 ALIASES += "endrst=\endverbatim"
+ALIASES += "inlinerst=\verbatim embed:rst:inline"
 {extra}
 """.strip()
 

diff --git a/documentation/source/markups.rst b/documentation/source/markups.rst
@@ -127,6 +127,38 @@ This will appropriately handle the leading slashes and render as:
 
 ----
 
+Inline rST
+~~~~~~~~~~
+
+.. cpp:namespace:: @ex_markups_inline
+
+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::
+
+   /// Some kind of method
+   ///
+   /// @param something a parameter
+   /// @returns the same value provided in something param
+   ///
+   /// @verbatim embed:rst:inline some inline text @endverbatim
+
+For these kinds of references, you can use an **embed:rst:inline** tag as
+shown in the above example.
+
+This will appropriately handle the leading slashes and render as:
+
+----
+
+.. doxygenfunction:: TestClass::rawInlineVerbatim
+   :project: rst
+
+.. doxygenfunction:: TestClass::rawVerbatim
+   :project: rst
+   :outline:
+
+----
+
 Aliases
 ~~~~~~~
 

diff --git a/examples/specific/rst.cfg b/examples/specific/rst.cfg
@@ -12,3 +12,4 @@ GENERATE_XML = YES
 
 ALIASES = "rst=\verbatim embed:rst"
 ALIASES += "endrst=\endverbatim"
+ALIASES += "inlinerst=\verbatim embed:rst:inline"
diff --git a/examples/specific/rst.h b/examples/specific/rst.h
@@ -12,7 +12,7 @@ class TestClass
     This is some funky non-XML compliant text: <& !><
 
     .. note::
-        
+
        This reStructuredText has been handled correctly.
     \endrst
 
@@ -67,6 +67,12 @@ class TestClass
     //////////////////////////////////////////////////////////////
     virtual void rawLeadingSlashesVerbatim(int something) const = 0;
 
+    /*!
+    Inserting an inline reStructuredText snippet.
+    Linking to another function: \inlinerst :cpp:func:`TestClass::rawVerbatim` \endrst
+    */
+    virtual void rawInlineVerbatim() const = 0;
+
     //! Brief description
     virtual void testFunction() const {};
 };