Add the log categories to the documentation

Also fix make distcheck, and fix several issues in the doc on my way

diff --git a/.gitignore b/.gitignore
index 83f5d6c..826ff7e 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -54,7 +54,7 @@ DartConfiguration.tcl
 TAGS
 Testing/
 Makefile
-bin/
+./bin/
 lib/
 manpages/
 build_*/

diff --git a/MANIFEST.in b/MANIFEST.in
index dc2eb7f..b2f3889 100644 (file)
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,8 +1,6 @@
 # This file lists the content of the python source package
 # Prepared in tools/cmake/Distrib.cmake
 include MANIFEST.in
-include doc/shared/fig/simgrid_modules.fig
-include doc/shared/fig/simgrid_modules2.fig
 include doc/webcruft/Paje_MSG_screenshot.jpg
 include doc/webcruft/Paje_MSG_screenshot_thn.jpg
 include doc/webcruft/SGicon.gif
@@ -1741,7 +1739,6 @@ include tools/MSG_visualization/colorize.pl
 include tools/MSG_visualization/trace2fig.pl
 include tools/address_sanitizer.supp
 include tools/doxygen/fig2dev_postprocessor.pl
-include tools/doxygen/xbt_log_extract_hierarchy.pl
 include tools/fix-paje-trace.sh
 include tools/generate-dwarf-functions
 include tools/graphicator/graphicator.cpp
@@ -1808,6 +1805,7 @@ include doc/doxygen/uhood.doc
 include doc/doxygen/uhood_arch.doc
 include doc/doxygen/uhood_switch.doc
 include docs/Build.sh
+include docs/bin/extract_logs_hierarchy.pl
 include docs/find-missing.ignore
 include docs/find-missing.py
 include docs/ignored_symbols
@@ -2782,7 +2780,6 @@ include tools/cmake/test_prog/prog_stacksetup.c
 include tools/cmake/test_prog/prog_tsan.cpp
 include tools/doxygen/fig2dev_postprocessor.pl
 include tools/doxygen/list_routing_models_examples.sh
-include tools/doxygen/xbt_log_extract_hierarchy.pl
 include tools/graphicator/CMakeLists.txt
 include tools/lualib.patch
 include tools/smpi/generate_smpi_defines.pl

diff --git a/docs/Build.sh b/docs/Build.sh
index cc536cb..4ea9d3e 100755 (executable)
--- a/docs/Build.sh
+++ b/docs/Build.sh
@@ -7,19 +7,30 @@
 # Python needs to find simgrid on my machine, but not ctest -- sorry for the hack
 if [ -e /opt/simgrid ] ; then chmod +x /opt/simgrid; fi
 
-set -ex
+set -e
 set -o pipefail
 
 if [ "x$1" != 'xdoxy' ] && [ -e build/xml ] ; then
   echo "Doxygen not rerun: 'doxy' was not provided as an argument"
 else
+  set -x
   rm -rf build/xml source/api/
   (cd source; doxygen 2>&1; cd ..) | grep -v "is not documented." #   XXXXX Reduce the verbosity for now
+  set +x
 fi
 
+if [ "x$1" != 'xlogs' ] && [ -e build/log_categories.rst ] ; then
+  echo "Log categories not extracted: 'logs' was not provided as an argument"
+else
+  set -x
+  perl ./bin/extract_logs_hierarchy.pl ../ > build/log_categories.rst
+  set +x
+fi 
+
 if [ "x$1" != 'xjava' ] && [ -e source/java ] ; then
   echo "javasphinx not rerun: 'java' was not provided as an argument"
 else
+  set -x
   rm -rf source/java
   
   # Use that script without installing javasphinx: javasphinx-apidoc --force -o source/java/ ../src/bindings/java/org/simgrid/msg

diff --git a/tools/doxygen/xbt_log_extract_hierarchy.pl b/docs/bin/extract_logs_hierarchy.pl
similarity index 88%
rename from tools/doxygen/xbt_log_extract_hierarchy.pl
rename to docs/bin/extract_logs_hierarchy.pl
index a45c847..a6f3dfe 100755 (executable)
--- a/tools/doxygen/xbt_log_extract_hierarchy.pl
+++ b/docs/bin/extract_logs_hierarchy.pl
@@ -11,9 +11,10 @@ use warnings;
 
 my $debug = 0;
 
-print "/* Generated file, do not edit */\n";
-print "/** \\addtogroup XBT_log_cats\n";
-print "        \@{\n";
+print ".. Generated file, do not edit \n\n";
+print ".. _logging_categories:\n\n";
+print "Existing categories\n";
+print "===================\n\n";
 
 # Search for calls to macros defining new channels, and prepare the tree representation
 my %ancestor;
@@ -91,13 +92,22 @@ my %used;
 sub display_subtree {
     my $name=shift;
     my $indent=shift;
-
+    
     $used{$name} = 1;
     unless ($name eq "XBT_LOG_ROOT_CAT") { # do not display the root
        print "$indent - $name: ".($desc{$name}|| "(undocumented)")."\n";
     }
+
+    my $state = 0; # 0: before the sublist; 1, within; 2: after
     foreach my $cat (grep {$ancestor{$_} eq $name} sort keys %ancestor) {
-       display_subtree($cat,"$indent  ");
+       if ($state == 0) {
+           $state = 1;
+           print "\n";
+       }
+       display_subtree($cat, $name eq "XBT_LOG_ROOT_CAT" ? $indent: "$indent  ");
+    }
+    if ($state != 0) {
+       print "\n";
     }
 }
 
@@ -107,4 +117,4 @@ map {
     warn "Category $_ does not seem to be connected to the root (anc=$ancestor{$_})\n";
 } grep {!defined $used{$_}} sort keys %ancestor;
 
-print "@}*/\n";
+print "\n";

diff --git a/docs/source/The_XBT_toolbox.rst b/docs/source/The_XBT_toolbox.rst
index 3e12ce2..5866ff1 100644 (file)
--- a/docs/source/The_XBT_toolbox.rst
+++ b/docs/source/The_XBT_toolbox.rst
@@ -22,32 +22,32 @@ Declaring categories
 ====================
 
 Typically, there will be a category for each module of the implementation, so that users can independently control the logging for each module.
-Refer to the :ref:`XBT_log_cats` section for a list of all existing categories in SimGrid.
+Refer to the :ref:`logging_categories` section for a list of all existing categories in SimGrid.
 
-.. cpp:function:: XBT_LOG_NEW_CATEGORY(category, description)
+.. c:macro:: XBT_LOG_NEW_CATEGORY(category, description)
 
    Creates a new category that is not within any existing categories. It will be located right below the ``root`` category.
    ``category`` must be a valid identifier (such as ``mycat``) with no quote or anything. It should also be unique over the whole binary.
    ``description`` must be a string, between quotes.
 
-.. cpp:function:: XBT_LOG_NEW_SUBCATEGORY(category, parent_category, description)
+.. c:macro:: XBT_LOG_NEW_SUBCATEGORY(category, parent_category, description)
 
    Creates a new category under the provided ``parent_category``.
 
-.. cpp:function:: XBT_LOG_NEW_DEFAULT_CATEGORY(category, description)
+.. c:macro:: XBT_LOG_NEW_DEFAULT_CATEGORY(category, description)
 
-   Similar to :cpp:func:`XBT_LOG_NEW_CATEGORY`, and the created category is the default one in the current source file.
+   Similar to :c:macro:`XBT_LOG_NEW_CATEGORY`, and the created category is the default one in the current source file.
 
-.. cpp:function:: XBT_LOG_NEW_DEFAULT_SUBCATEGORY(category, parent_category, description)
+.. c:macro:: XBT_LOG_NEW_DEFAULT_SUBCATEGORY(category, parent_category, description)
 
-   Similar to :cpp:func:`XBT_LOG_NEW_SUBCATEGORY`, and the created category is the default one in the current source file.
+   Similar to :c:macro:`XBT_LOG_NEW_SUBCATEGORY`, and the created category is the default one in the current source file.
 
-.. cpp:function:: XBT_LOG_EXTERNAL_CATEGORY(category)
+.. c:macro:: XBT_LOG_EXTERNAL_CATEGORY(category)
 
    Make an external category (i.e., a category declared in another source file) visible from this source file. 
    In each source file, at most one one category can be the default one.
 
-.. cpp:function:: XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(category)
+.. c:macro:: XBT_LOG_EXTERNAL_DEFAULT_CATEGORY(category)
 
    Use an external category as default category in this source file.
 
@@ -57,27 +57,27 @@ Logging messages
 Default category
 ----------------
 
-.. cpp:function:: XBT_CRITICAL(format_string, parameters...)
+.. c:macro:: XBT_CRITICAL(format_string, parameters...)
 
    Report a fatal error to the default category.
 
-.. cpp:function:: XBT_ERROR(format_string, parameters...)
+.. c:macro:: XBT_ERROR(format_string, parameters...)
 
    Report an error to the default category.
 
-.. cpp:function:: XBT_WARN(format_string, parameters...)
+.. c:macro:: XBT_WARN(format_string, parameters...)
 
    Report a warning or an important information to the default category.
 
-.. cpp:function:: XBT_INFO(format_string, parameters...)
+.. c:macro:: XBT_INFO(format_string, parameters...)
 
    Report an information of regular importance to the default category.
 
-.. cpp:function:: XBT_VERB(format_string, parameters...)
+.. c:macro:: XBT_VERB(format_string, parameters...)
 
    Report a verbose information to the default category.
 
-.. cpp:function:: XBT_DEBUG(format_string, parameters...)
+.. c:macro:: XBT_DEBUG(format_string, parameters...)
 
    Report a debug-only information to the default category.
 
@@ -86,52 +86,52 @@ the compiler will warn you for unmatched arguments, such as passing a pointer wh
 
 Here is an example: ``XBT_WARN("Values are: %d and '%s'", 5, "oops");``
 
-.. cpp:function:: XBT_IN(format_string, parameters...)
+.. c:macro:: XBT_IN(format_string, parameters...)
 
    Report that the execution flow enters a given function (which name is displayed automatically).
 
-.. cpp:function:: XBT_OUT(format_string, parameters...)
+.. c:macro:: XBT_OUT(format_string, parameters...)
 
    Report that the execution flow exits a given function (which name is displayed automatically).
 
-.. cpp:function:: XBT_HERE(format_string, parameters...)
+.. c:macro:: XBT_HERE(format_string, parameters...)
 
    Report that the execution flow reaches a given location.
 
 Specific category
 -----------------
 
-.. cpp:function:: XBT_CCRITICAL(category, format_string, parameters...)
+.. c:macro:: XBT_CCRITICAL(category, format_string, parameters...)
 
    Report a fatal error to the specified ``category``.
 
-.. cpp:function:: XBT_CERROR(category, format_string, parameters...)
+.. c:macro:: XBT_CERROR(category, format_string, parameters...)
 
    Report an error to the specified ``category``.
 
-.. cpp:function:: XBT_CWARN(category, format_string, parameters...)
+.. c:macro:: XBT_CWARN(category, format_string, parameters...)
 
    Report a warning or an important information to the specified ``category``.
 
-.. cpp:function:: XBT_CINFO(category, format_string, parameters...)
+.. c:macro:: XBT_CINFO(category, format_string, parameters...)
 
    Report an information of regular importance to the specified ``category``.
 
-.. cpp:function:: XBT_CVERB(category, format_string, parameters...)
+.. c:macro:: XBT_CVERB(category, format_string, parameters...)
 
    Report a verbose information to the specified ``category``.
 
-.. cpp:function:: XBT_CDEBUG(category, format_string, parameters...)
+.. c:macro:: XBT_CDEBUG(category, format_string, parameters...)
 
    Report a debug-only information to the specified ``category``.
 
-Of course, the specified category must be visible from this source file, either because it was created there (e.g. with :cpp:func:`XBT_LOG_NEW_CATEGORY`) or because it was made
-visible with :cpp:func:`XBT_LOG_EXTERNAL_CATEGORY`.
+Of course, the specified category must be visible from this source file, either because it was created there (e.g. with :c:macro:`XBT_LOG_NEW_CATEGORY`) or because it was made
+visible with :c:macro:`XBT_LOG_EXTERNAL_CATEGORY`.
 
 Other functions
 ===============
 
-.. cpp:function:: XBT_LOG_ISENABLED(category, priority)
+.. c:macro:: XBT_LOG_ISENABLED(category, priority)
 
    Returns true if that category displays the messages of that priority. It's useful to compute a value that is used only in the logging, such as the textual representation of a
    non-trivial object.
@@ -139,16 +139,18 @@ Other functions
    The specified priority must be one of ``xbt_log_priority_trace``, ``xbt_log_priority_debug``, ``xbt_log_priority_verbose``, ``xbt_log_priority_info``,
    ``xbt_log_priority_warning``, ``xbt_log_priority_error`` or ``xbt_log_priority_critical``.
 
-.. cpp:function:: void xbt_log_control_set(const char* setting)
+.. c:function:: void xbt_log_control_set(const char* setting)
 
    Sets the provided ``setting`` as if it was passed in a ``--log`` command-line parameter.
 
 You should not use any of the macros which name starts with '_'.
 
+.. include:: ../build/log_categories.rst
+
 Full example
 ============
 
-.. code-block:: cpp
+.. code-block:: C
 
    #include "xbt/log.h"
 

diff --git a/tools/CMakeLists.txt b/tools/CMakeLists.txt
index 426d36c..03f2bdc 100644 (file)
--- a/tools/CMakeLists.txt
+++ b/tools/CMakeLists.txt
@@ -5,7 +5,6 @@ set(bin_files ${bin_files}    ${CMAKE_CURRENT_SOURCE_DIR}/fix-paje-trace.sh
                               ${CMAKE_CURRENT_SOURCE_DIR}/simgrid_update_xml.pl
                               ${CMAKE_CURRENT_SOURCE_DIR}/simgrid_convert_TI_traces.py
                               ${CMAKE_CURRENT_SOURCE_DIR}/doxygen/fig2dev_postprocessor.pl
-                              ${CMAKE_CURRENT_SOURCE_DIR}/doxygen/xbt_log_extract_hierarchy.pl
                               ${CMAKE_CURRENT_SOURCE_DIR}/MSG_visualization/colorize.pl
                               ${CMAKE_CURRENT_SOURCE_DIR}/MSG_visualization/trace2fig.pl          PARENT_SCOPE)
 

diff --git a/tools/cmake/DefinePackages.cmake b/tools/cmake/DefinePackages.cmake
index b5cb699..8676c72 100644 (file)
--- a/tools/cmake/DefinePackages.cmake
+++ b/tools/cmake/DefinePackages.cmake
@@ -893,6 +893,7 @@ set(DOC_SOURCES
   docs/manpages/tesh.pod
 
   docs/Build.sh
+  docs/bin/extract_logs_hierarchy.pl
   docs/requirements.txt
   docs/source/conf.py
   docs/source/Doxyfile
@@ -978,14 +979,8 @@ set(DOC_SOURCES
   CITATION.bib
   )
 
-set(DOC_FIGS
-  ${CMAKE_HOME_DIRECTORY}/doc/shared/fig/simgrid_modules.fig
-  ${CMAKE_HOME_DIRECTORY}/doc/shared/fig/simgrid_modules2.fig
-  )
-
 set(DOC_TOOLS
   tools/doxygen/fig2dev_postprocessor.pl
-  tools/doxygen/xbt_log_extract_hierarchy.pl
   tools/doxygen/list_routing_models_examples.sh
   )
 

diff --git a/tools/cmake/Distrib.cmake b/tools/cmake/Distrib.cmake
index 72d8a98..e8ca613 100644 (file)
--- a/tools/cmake/Distrib.cmake
+++ b/tools/cmake/Distrib.cmake
@@ -170,7 +170,6 @@ set(source_to_pack
   ${EXTRA_DIST}
   ${CMAKE_SOURCE_FILES}
   ${CMAKEFILES_TXT}
-  ${DOC_FIGS}
   ${DOC_IMG}
   ${DOC_SOURCES}
   ${DOC_TOOLS}

diff --git a/tools/cmake/Documentation.cmake b/tools/cmake/Documentation.cmake
index da57877..df4b530 100644 (file)
--- a/tools/cmake/Documentation.cmake
+++ b/tools/cmake/Documentation.cmake
@@ -19,7 +19,7 @@ find_path(FIG2DEV_PATH  NAMES fig2dev  PATHS NO_DEFAULT_PATHS)
 if(enable_documentation)
   ADD_CUSTOM_TARGET(documentation
     COMMENT "Generating the SimGrid documentation..."
-    DEPENDS ${DOC_SOURCES} ${DOC_FIGS} ${source_doxygen}
+    DEPENDS ${DOC_SOURCES} ${source_doxygen}
     COMMAND ${CMAKE_COMMAND} -E make_directory   ${CMAKE_BINARY_DIR}/doc/doxygen
     COMMAND ${CMAKE_COMMAND} -E make_directory   ${CMAKE_BINARY_DIR}/doc/example_lists
     COMMAND ${CMAKE_COMMAND} -E remove_directory ${CMAKE_BINARY_DIR}/doc/html
@@ -48,12 +48,6 @@ if(enable_documentation)
 
   configure_file(${CMAKE_HOME_DIRECTORY}/doc/Doxyfile.in ${CMAKE_BINARY_DIR}/doc/Doxyfile @ONLY)
 
-  foreach(file ${DOC_FIGS})
-    string(REPLACE ".fig" ".png" tmp_file ${file})
-    string(REPLACE "${CMAKE_HOME_DIRECTORY}/doc/shared/fig/" "${CMAKE_BINARY_DIR}/doc/html/" tmp_file ${tmp_file})
-    ADD_CUSTOM_COMMAND(TARGET documentation  COMMAND ${FIG2DEV_PATH}/fig2dev -Lpng -S 4 ${file} ${tmp_file})
-  endforeach()
-
   foreach(file ${DOC_IMG})
     ADD_CUSTOM_COMMAND(TARGET documentation COMMAND ${CMAKE_COMMAND} -E copy ${file} ${CMAKE_BINARY_DIR}/doc/html/)
   endforeach()
@@ -61,9 +55,6 @@ if(enable_documentation)
   ADD_CUSTOM_COMMAND(TARGET documentation
     COMMAND ${FIG2DEV_PATH}/fig2dev -Lmap ${CMAKE_HOME_DIRECTORY}/doc/shared/fig/simgrid_modules.fig | perl -pe 's/imagemap/simgrid_modules/g'| perl -pe 's/<IMG/<IMG style=border:0px/g' | ${CMAKE_HOME_DIRECTORY}/tools/doxygen/fig2dev_postprocessor.pl > ${CMAKE_BINARY_DIR}/doc/simgrid_modules.map
     COMMAND pwd
-    COMMAND ${CMAKE_COMMAND} -E echo "XX Generate the index files"
-    COMMAND ${CMAKE_COMMAND} -E remove ${CMAKE_BINARY_DIR}/doc/doxygen/logcategories.doc
-    COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/xbt_log_extract_hierarchy.pl ${CMAKE_HOME_DIRECTORY} > ${CMAKE_BINARY_DIR}/doc/doxygen/logcategories.doc
     COMMAND ${CMAKE_COMMAND} -E echo "XX Generate list of files in examples/ for routing models"
     COMMAND ${CMAKE_COMMAND} -E make_directory ${CMAKE_BINARY_DIR}/doc/example_lists/
     COMMAND ${CMAKE_HOME_DIRECTORY}/tools/doxygen/list_routing_models_examples.sh Floyd > ${CMAKE_BINARY_DIR}/doc/example_lists/example_filelist_routing_floyd