From 41f77a3fb7663b4728309769c57cc075e3d7a564 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Wed, 25 Apr 2018 08:21:30 +0200 Subject: [PATCH] doc: a new Troubleshooting section for the Doxygen theme. So I don't have to repeat myself :) --- doc/doxygen.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 102 insertions(+), 1 deletion(-) diff --git a/doc/doxygen.rst b/doc/doxygen.rst index b4d0adf5..82ea3c65 100644 --- 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 `, 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. ` +- 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 `_ with + given snippet and all relevant info (especially Doxygen version). Or ask + in the `Gitter chat `_. 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`_ =========================== -- 2.30.2