doc: a new Troubleshooting section for the Doxygen theme.

So I don't have to repeat myself :)

diff --git a/doc/doxygen.rst b/doc/doxygen.rst
index b4d0adf5aeb2523581a6c94833e6375ce5197ad2..82ea3c650419e20698b40bd20bcd0e6622056ed6 100644 (file)
--- a/doc/doxygen.rst
+++ b/doc/doxygen.rst
@@ -128,6 +128,9 @@ It will run ``doxygen`` to generate the XML output, processes it and generates
 the HTML output in the configured output directory. After the script is done,
 just open generated ``index.html`` to see the result.
 
+If you see something unexpected or not see something expected, check the
+`Troubleshooting`_ section below.
+
 `Features`_
 ===========
 
@@ -149,7 +152,8 @@ just open generated ``index.html`` to see the result.
     member listing
 -   Files, directories and symbols that don't have any documentation are not
     present in the output at all. This is done in order to encourage good
-    documentation practices.
+    documentation practices --- having the output consist of an actual
+    human-written documentation instead of just autogenerated lists.
 -   Table of contents is generated for compound references as well, containing
     all sections of detailed description together with anchors to member
     listings
@@ -852,6 +856,103 @@ Options:
 -   ``--sort-globbed-files`` --- sort globbed files for better reproducibility
 -   ``--debug`` --- verbose debug output. Useful for debugging.
 
+`Troubleshooting`_
+==================
+
+`Generated output is (mostly) empty`_
+-------------------------------------
+
+As stated in the `Features <#important-differences-to-stock-html-output>`_
+section above; files, directories and symbols with no documentation are not
+present in the output at all. In particular, when all your sources are under a
+subdirectory and/or a namespace and that subdirectory / namespace is not
+documented, the file / symbol tree will not show anything.
+
+A simple ``@brief`` entry is enough to fix this. For example, if you have a
+:cpp:`MorningCoffee::CleanCup` class that's available from
+:cpp:`#include <MorningCoffee/CleanCup.h>`, these documentation blocks are
+enough to have the directory, file, namespace and also the class appear in the
+file / symbol tree:
+
+.. code:: c++
+
+    /** @dir MorningCoffee
+     * @brief Namespace @ref MorningCoffee
+     */
+    /** @namespace MorningCoffee
+     * @brief The Morning Coffee library
+     */
+
+.. code:: c++
+
+    // CleanCup.h
+
+    /** @file
+     * @brief Class @ref CleanCup
+     */
+
+    namespace MorningCoffee {
+
+        /**
+         * @brief A clean cup
+         */
+        class CleanCup {
+
+        ...
+
+To help you debugging this, run ``dox2html5.py`` with the ``--debug`` option.
+and look for entries that look like below. Because there are many false
+positives, this information is not present in the non-verbose output.
+
+.. code:: shell-session
+
+    DEBUG:root:dir_22305cb0964bbe63c21991dd2265ce48.xml: neither brief nor
+    detailed description present, skipping
+
+Besides the above, the output will be mostly empty also if you have the
+:ini:`GENERATE_SUBDIRS` Doxyfile option enabled. This option causes Doxygen to
+scatter the XML files across numerous subdirectories to work around limits of
+ancient filesystems. m.css doesn't support it and probably never will, set it
+back to ``NO`` it in your ``Doxyfile-mcss`` override. For easier debugging,
+m.css will warn if it finds this option enabled.
+
+`Output is not styled`_
+-----------------------
+
+If your ``Doxyfile`` contains a non-empty :ini:`HTML_EXTRA_STYLESHEET` option,
+m.css will use CSS files from there instead of the builtin ones. Either
+override to an empty value it in your ``Doxyfile-mcss`` or specify proper CSS
+files explicitly as mentioned in the `Theme selection`_ section.
+
+`Generating takes too long, crashes, asserts or generally fails`_
+-----------------------------------------------------------------
+
+The XML output generated by Doxygen is underspecified and unnecessarily
+complex, so it might very well happen that your documentation triggers some
+untested code path. The script is designed to fail early and hard instead of
+silently continuing and producing wrong output --- if you see an assertion
+failure or a crash or things seem to be stuck, you can do the following:
+
+-   Re-run the script with the ``--debug`` option. That will list what XML file
+    is being processed at the moment and helps you narrow down the issue to a
+    particular file.
+-   At the moment, math formula rendering is not batched and takes very long,
+    as LaTeX is started separately for every occurrence.
+    :gh:`Help in this area is welcome. <mosra/m.css#32>`
+-   Try with a freshly generated ``Doxyfile``. If it stops happening, the
+    problem might be related to some configuration option (but maybe also an
+    alias or preprocessor :cpp:`#define` that's not defined anymore)
+-   m.css currently expects only C++ input. If you have Python or some other
+    language on input, it will get very confused very fast. This can be also
+    caused by a file being included by accident, restrict the :ini:`INPUT` and
+    :ini:`FILE_PATTERNS` options to prevent that.
+-   Try to narrow the problem down to a small code snippet and
+    `submit a bug report <https://github.com/mosra/m.css/issues/new>`_ with
+    given snippet and all relevant info (especially Doxygen version). Or ask
+    in the `Gitter chat <https://gitter.im/mosra/m.css>`_. If I'm not able to
+    provide a fix right away, there's a great chance I've already seen such
+    problem and can suggest a workaround at least.
+
 `Customizing the template`_
 ===========================