[#1945] address review

- add DBGLVL_TRACE_MAX
- generate debug-messages.rst automatically on make -C doc/sphinx

Author: andrei-pavel

doc/sphinx/Makefile.am

@@ -61,9 +61,9 @@ api_files =
 include $(top_srcdir)/src/share/api/api_files.mk
 
 if HAVE_PDFLATEX
-all: kea-messages.rst html mans pdf text
+all: debug-messages.rst kea-messages.rst html mans pdf text
 else
-all: kea-messages.rst html mans text
+all: debug-messages.rst kea-messages.rst html mans text
 endif
 
 # build the list of message files
@@ -73,6 +73,10 @@ mes_files.mk: mes-files.txt
 mes-files.txt:
 	@find ../.. -type f -name '*.mes' | sort -V | sed 's#^../../##g' > $@
 
+# Used in official build process. debug-messages.rst is generated via ./tools/check-messages.py -g.
+$(srcdir)/debug-messages.rst: $(srcdir)/../../tools/check-messages.py
+	$(PYTHON) $< --generate-debug-messages-page
+
 # Used in official build process. kea-messages.rst is generated via mes2doc.py.
 $(srcdir)/kea-messages.rst: mes2doc.py
 	$(PYTHON) $(srcdir)/mes2doc.py -o $@
@@ -222,7 +226,7 @@ update-python-dependencies: ./src/requirements.in
 clean-local:
 	rm -rf $(sphinxbuilddir)
 	rm -f $(srcdir)/mes-files.txt $(srcdir)/api-files.txt
-	rm -f $(srcdir)/kea-messages.rst $(srcdir)/api.rst
+	rm -f $(srcdir)/debug-messages.rst $(srcdir)/kea-messages.rst $(srcdir)/api.rst
 	rm -f $(srcdir)/arm/platforms.rst
 
 .PHONY: all pdf html mans update-python-dependencies uml uml-to-png uml-to-svg format-svgs uml-to-txt

src/lib/log/log_dbglevels.cc

@@ -22,6 +22,7 @@ extern const int DBGLVL_TRACE_DETAIL = 50;
 extern const int DBGLVL_TRACE_DETAIL_DATA = 55;
 extern const int DBGLVL_TRACE_TECHNICAL = 70;
 extern const int DBGLVL_TRACE_TECHNICAL_DATA = 90;
+extern const int DBGLVL_TRACE_MAX = 99;
 
 }  // namespace log
 }  // namespace isc

src/lib/log/log_dbglevels.h

@@ -83,6 +83,9 @@ extern const int DBGLVL_TRACE_TECHNICAL;
 /// @brief Trace data associated with technical operations.
 extern const int DBGLVL_TRACE_TECHNICAL_DATA;
 
+/// @brief The highest level of debug logging.
+extern const int DBGLVL_TRACE_MAX;
+
 }  // log namespace
 }  // isc namespace
 

tools/check-messages.py

@@ -54,10 +54,12 @@ def check_duplicate_occurences(occurences):
 
 
 def check_unlogged_messages(messages, autofix):
-    all_source_files = set(pathlib.Path('.').glob('**/*.cc')) \
-        - set(pathlib.Path('.').glob('**/*messages.cc')) \
-        | set(pathlib.Path('.').glob('**/*.h')) \
-        - set(pathlib.Path('.').glob('**/*messages.h'))
+    parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
+    root_dir = f'{parent_dir}/..'
+    all_source_files = set(pathlib.Path(root_dir).glob('**/*.cc')) \
+        - set(pathlib.Path(root_dir).glob('**/*messages.cc')) \
+        | set(pathlib.Path(root_dir).glob('**/*.h')) \
+        - set(pathlib.Path(root_dir).glob('**/*messages.h'))
     all_source_code = ''
     for file in all_source_files:
         with open(file, 'r', encoding='utf-8') as f:
@@ -216,6 +218,8 @@ def main():
                                      formatter_class=argparse.RawTextHelpFormatter)
     parser.add_argument('-a', '--autofix', action='store_true',
                         help='Autofix unused messages and debug log levels in docs.')
+    parser.add_argument('-g', '--generate-debug-messages-page', action='store_true',
+                        help='Generate the debug-messages.rst file included in the ARM.')
     args = parser.parse_args()
 
     # Initializations
@@ -229,7 +233,9 @@ def main():
     log_pattern = re.compile(r'\b(LOG_DEBUG|LOG_ERROR|LOG_FATAL|LOG_INFO|LOG_WARN)\(')
 
     # Process .mes files.
-    mes_files = sorted(pathlib.Path('.').glob('**/*.mes'))
+    parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
+    root_dir = f'{parent_dir}/..'
+    mes_files = sorted(pathlib.Path(root_dir).glob('**/*.mes'))
     for mes_file in mes_files:
         with open(mes_file, 'r', encoding='utf-8') as f:
             current_message_id = None
@@ -265,8 +271,8 @@ def main():
                     }
 
     # Process .cc and .h files.
-    cc_files = sorted(pathlib.Path('.').glob('**/*.cc'))
-    h_files = sorted(pathlib.Path('.').glob('**/*.h'))
+    cc_files = sorted(pathlib.Path(root_dir).glob('**/*.cc'))
+    h_files = sorted(pathlib.Path(root_dir).glob('**/*.h'))
     cpp_files = cc_files + h_files
     for cpp_file in cpp_files:
         # Skip test files.
@@ -327,6 +333,11 @@ def main():
     for level in debug_levels:
         debug_levels[level] = int(debug_levels[level])
 
+    if args.autofix or args.generate_debug_messages_page:
+        generate_page_with_messages_printed_on_each_debug_level(messages, debug_levels)
+        if args.generate_debug_messages_page:
+            return
+
     # Get number of occurences for each message id.
     for line in log_lines:
         pos = 1
@@ -354,9 +365,6 @@ def main():
     # 7. Checks that the placeholder ids are consecutive, starting with 1, and unique in the same message definition.
     failure |= check_placeholder_ids(messages)
 
-    if args.autofix:
-        generate_page_with_messages_printed_on_each_debug_level(messages, debug_levels)
-
     if failure:
         sys.exit(1)