Add documentation page for doxygenpage directive

Add initial documentation with "doxygenpage" usage relying on previously
added xrefsect examples.

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

documentation/source/directives.rst

@@ -18,6 +18,7 @@ Directives & Config Variables
    file
    group
    autofile
+   page
 
 .. contents:: Table of Contents
 

documentation/source/page.rst

@@ -0,0 +1,60 @@
+
+.. _page-example:
+
+doxygenpage Directive
+=====================
+
+This directive generates the appropriate output for the contents of a doxygen
+page. A doxygen page is created for each "key" of every \\xrefitem command used
+for markup in the source comments. For more information check the
+`doxygen documentation`_.
+
+It takes the standard ``project`` and ``path`` options.
+
+::
+
+   .. doxygenpage:: <page name>
+      :project: ...
+      :path: ...
+
+.. _doxygen documentation: https://www.doxygen.nl/manual/commands.html#cmdxrefitem
+
+.. contents::
+
+
+Basic Example
+-------------
+
+.. cpp:namespace:: @ex_page_basic
+
+The plain ``doxygenpage`` directive will output the page name and description
+and any variable entries which were defined to be part of this page (with an
+\xrefitem usage).
+
+.. code-block:: rst
+
+   .. doxygenpage:: xrefsample
+      :project: xrefsect
+
+It produces this output:
+
+.. doxygenpage:: xrefsample
+   :project: xrefsect
+
+
+Failing Example
+---------------
+
+.. cpp:namespace:: @ex_page_failing
+
+This intentionally fails:
+
+.. code-block:: rst
+
+   .. doxygengroup:: madeuppage
+      :project: xrefsect
+
+It produces the following warning message:
+
+.. warning:: Cannot find file "madeuppage" in doxygen xml output for project
+             "xrefsect" from directory: ../../examples/specific/xrefsect/xml/