From: Martin Quinson Date: Sun, 24 Jan 2021 17:26:27 +0000 (+0100) Subject: Add the log categories to the documentation X-Git-Tag: v3.27~542 X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/97638e67686e0e77ae56572ab433b1f9a45406a0 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 83f5d6cdae..826ff7e890 100644 --- 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 dc2eb7f385..b2f38898e4 100644 --- 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 cc536cb689..4ea9d3e082 100755 --- 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 a45c847467..a6f3dfe8b4 100755 --- 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 3e12ce2019..5866ff156c 100644 --- 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 426d36c5dd..03f2bdc5a9 100644 --- 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 b5cb699af5..8676c722e5 100644 --- 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 72d8a98642..e8ca61322f 100644 --- 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 da578778a1..df4b53084b 100644 --- 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/ ${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