Add table examples to documentation

This adds the examples found on Doxygen's website for describing tables
in Markdown and Doxygen syntax.

PS: The examples that include rowspan/colspan were left commented out in
the rST because they are currently breaking latex generation (although
"make html" works).

Signed-off-by: Fabio Utzig <[email protected]>

documentation/source/conf.py

@@ -204,6 +204,7 @@
     "programlisting":"../../examples/specific/programlisting/xml/",
     "image":"../../examples/specific/image/xml/",
     "lists":"../../examples/specific/lists/xml/",
+    "tables":"../../examples/specific/tables/xml/",
     "group":"../../examples/specific/group/xml/",
     "union":"../../examples/specific/union/xml/",
     "qtsignalsandslots":"../../examples/specific/qtsignalsandslots/xml/",

documentation/source/index.rst

@@ -69,6 +69,7 @@ Features
    customcss
    groups
    lists
+   tables
    template
 
 Contributing

documentation/source/tables.rst

@@ -0,0 +1,84 @@
+Tables
+======
+
+Breathe has support for tables in the doxygen documentation. They are output as
+follows.
+
+.. cpp:namespace:: @ex_tables_simple
+
+A simple Markdown syntax table ::
+
+   .. doxygenclass:: Table_1
+      :project: tables
+
+It renders as:
+
+----
+
+.. doxygenclass:: Table_1
+   :project: tables
+
+----
+
+.. cpp:namespace:: @ex_tables_aligned
+
+A Markdown syntax table with alignment ::
+
+   .. doxygenclass:: Table_2
+      :project: tables
+
+It renders as:
+
+----
+
+.. doxygenclass:: Table_2
+   :project: tables
+
+..
+    ----
+
+    .. cpp:namespace:: @ex_tables_rowspan
+
+    A Markdown syntax table with rowspan (and alignment) ::
+
+       .. doxygenclass:: Table_3
+          :project: tables
+
+    It renders as:
+
+    ----
+
+    .. doxygenclass:: Table_3
+       :project: tables
+
+    ----
+
+    .. cpp:namespace:: @ex_tables_colspan
+
+    A Markdown syntax table with colspan (and alignment) ::
+
+       .. doxygenclass:: Table_4
+          :project: tables
+
+    It renders as:
+
+    ----
+
+    .. doxygenclass:: Table_4
+       :project: tables
+
+    ----
+
+    .. cpp:namespace:: @ex_tables_doxygen
+
+    A Doxygen syntax table ::
+
+       .. doxygenclass:: Table_5
+          :project: tables
+
+    It renders as:
+
+    ----
+
+    .. doxygenclass:: Table_5
+       :project: tables

examples/specific/Makefile

@@ -23,7 +23,7 @@ projects  = nutshell alias rst inline namespacefile array inheritance \
 			image name union group struct struct_function qtsignalsandslots lists \
 			headings links parameters template_class template_class_non_type \
 			template_function template_type_alias template_specialisation \
-			enum define interface xrefsect \
+			enum define interface xrefsect tables \
 			cpp_anon cpp_enum cpp_union cpp_function cpp_friendclass \
 			cpp_inherited_members cpp_trailing_return_type \
 			c_file c_struct c_enum c_typedef c_macro c_union

examples/specific/tables.cfg

@@ -0,0 +1,11 @@
+PROJECT_NAME     = "Tables Option"
+OUTPUT_DIRECTORY = tables
+GENERATE_LATEX   = NO
+GENERATE_MAN     = NO
+GENERATE_RTF     = NO
+CASE_SENSE_NAMES = NO
+INPUT            = tables.h
+QUIET            = YES
+JAVADOC_AUTOBRIEF = YES
+GENERATE_HTML = NO
+GENERATE_XML = YES

examples/specific/tables.h

@@ -0,0 +1,96 @@
+/**
+ * \brief This is a simple Markdown table example.
+ *
+ * Following is a simple table using Markdown syntax.
+ *
+ * First Header  | Second Header
+ * ------------- | -------------
+ * Content Cell  | Content Cell
+ * Content Cell  | Content Cell
+ *
+ * And this is some more text.
+ */
+class Table_1
+{
+};
+
+/**
+ * \brief This is a Markdown table with alignment.
+ *
+ * Following is a table with alignment using Markdown syntax.
+ *
+ * | Right | Center | Left  |
+ * | ----: | :----: | :---- |
+ * | 10    | 10     | 10    |
+ * | 1000  | 1000   | 1000  |
+ *
+ * And this is some more text.
+ */
+class Table_2
+{
+};
+
+/**
+ * \brief This is a Markdown table with rowspan and alignment.
+ *
+ * Following is a table with rowspan and alignment using Markdown syntax.
+ *
+ * | Right | Center | Left  |
+ * | ----: | :----: | :---- |
+ * | 10    | 10     | 10    |
+ * | ^     | 1000   | 1000  |
+ *
+ * And this is some more text.
+ */
+class Table_3
+{
+};
+
+/**
+ * \brief This is a Markdown table with colspan and alignment.
+ *
+ * Following is a table with colspan and alignment using Markdown syntax.
+ *
+ * | Right | Center | Left  |
+ * | ----: | :----: | :---- |
+ * | 10    | 10     | 10    |
+ * | 1000  |||
+ *
+ * And this is some more text.
+ */
+class Table_4
+{
+};
+
+/**
+ * \brief This is a Doxygen table.
+ *
+ * Following is a table using Doxygen syntax (and all supported features).
+ *
+ * <table>
+ * <caption id="multi_row">Complex table</caption>
+ * <tr><th>Column 1                      <th>Column 2        <th>Column 3
+ * <tr><td rowspan="2">cell row=1+2,col=1<td>cell row=1,col=2<td>cell row=1,col=3
+ * <tr><td rowspan="2">cell row=2+3,col=2                    <td>cell row=2,col=3
+ * <tr><td>cell row=3,col=1                                  <td rowspan="2">cell row=3+4,col=3
+ * <tr><td colspan="2">cell row=4,col=1+2
+ * <tr><td>cell row=5,col=1              <td colspan="2">cell row=5,col=2+3
+ * <tr><td colspan="2" rowspan="2">cell row=6+7,col=1+2      <td>cell row=6,col=3
+ * <tr>                                                      <td>cell row=7,col=3
+ * <tr><td>cell row=8,col=1              <td>cell row=8,col=2\n
+ *   <table>
+ *     <tr><td>Inner cell row=1,col=1<td>Inner cell row=1,col=2
+ *     <tr><td>Inner cell row=2,col=1<td>Inner cell row=2,col=2
+ *   </table>
+ *   <td>cell row=8,col=3
+ *   <ul>
+ *     <li>Item 1
+ *     <li>Item 2
+ *   </ul>
+ * </table>
+ *
+ * And this is some more text.
+ */
+class Table_5
+{
+};