Skip to content

Commit 317af48

Browse files
committed
[#1945] address review
- generate kea-messages.rst automatically on make -C doc/sphinx - add disclaimer header that debug-messages.rst and kea-messages.rst are generated - minor changes to debug level variable names - do not write section "Messages printed" in tools/check-messages.py if there are no messages
1 parent bf7753a commit 317af48

File tree

10 files changed

+37
-19
lines changed

10 files changed

+37
-19
lines changed

doc/sphinx/Makefile.am

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,9 +61,9 @@ api_files =
6161
include $(top_srcdir)/src/share/api/api_files.mk
6262

6363
if HAVE_PDFLATEX
64-
all: html mans pdf text
64+
all: kea-messages.rst html mans pdf text
6565
else
66-
all: html mans text
66+
all: kea-messages.rst html mans text
6767
endif
6868

6969
# build the list of message files
@@ -73,8 +73,7 @@ mes_files.mk: mes-files.txt
7373
mes-files.txt:
7474
@find ../.. -type f -name '*.mes' | sort -V | sed 's#^../../##g' > $@
7575

76-
# this rule is only used for development purposes and is not used in official
77-
# build process as kea-messages.rst is always generated via sphinx's conf.py
76+
# Used in official build process. kea-messages.rst is generated via mes2doc.py.
7877
$(srcdir)/kea-messages.rst: mes2doc.py
7978
$(PYTHON) $(srcdir)/mes2doc.py -o $@
8079

doc/sphinx/debug-messages.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
..
2+
File generated by "./tools/check-messages.py -a". Do not edit by hand.
3+
14
Messages printed on debuglevel 0
25
================================
36

doc/sphinx/kea-messages.rst

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
1+
..
2+
File generated by "doc/sphinx/mes2doc.py" or by "make -C doc/sphinx". Do not edit by hand.
3+
14
.. _kea-messages:
25

36
###################

doc/sphinx/mes2doc.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,10 @@ def read_input_files(files):
7878

7979

8080
def generate_rst(messages):
81-
rst = '''.. _kea-messages:
81+
rst = '..\n'
82+
rst += ' File generated by "doc/sphinx/mes2doc.py" or by "make -C doc/sphinx". Do not edit by hand.\n\n'
83+
84+
rst += '''.. _kea-messages:
8285
8386
###################
8487
Kea Messages Manual

src/bin/dhcp4/dhcp4_messages.mes

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -980,13 +980,13 @@ that the hint hasn't been sent.
980980

981981
% DHCP4_REQUIRED_CLASS_EVAL_ERROR %1: Expression '%2' evaluated to %3
982982
This error message indicates that there a problem was encountered while
983-
evaluating an expression of a client class that was marked as required.
983+
evaluating an expression of a required client class that was marked as required.
984984
A description of the problem is printed.
985985

986986
% DHCP4_REQUIRED_CLASS_EVAL_RESULT %1: Expression '%2' evaluated to %3
987987
Logged at debug log level 50.
988-
This debug message indicates that the expression of a client class has been
989-
successfully evaluated. The client class name and the result value of the
988+
This debug message indicates that the expression of a required client class has
989+
been successfully evaluated. The client class name and the result value of the
990990
evaluation are printed.
991991

992992
% DHCP4_RESERVATIONS_LOOKUP_FIRST_ENABLED Multi-threading is enabled and host reservations lookup is always performed first.

src/bin/dhcp6/dhcp6_messages.mes

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -985,13 +985,13 @@ expected IAID and IAID found respectively.
985985

986986
% DHCP6_REQUIRED_CLASS_EVAL_ERROR %1: Expression '%2' evaluated to %3
987987
This error message indicates that there a problem was encountered while
988-
evaluating an expression of a client class that was marked as required.
988+
evaluating an expression of a required client class that was marked as required.
989989
A description of the problem is printed.
990990

991991
% DHCP6_REQUIRED_CLASS_EVAL_RESULT %1: Expression '%2' evaluated to %3
992992
Logged at debug log level 50.
993-
This debug message indicates that the expression of a client class has been
994-
successfully evaluated. The client class name and the result value of the
993+
This debug message indicates that the expression of a required client class has
994+
been successfully evaluated. The client class name and the result value of the
995995
evaluation are printed.
996996

997997
% DHCP6_REQUIRED_OPTIONS_CHECK_FAIL %1: %2 message received from %3 failed the following check: %4

src/lib/asiodns/io_fetch.cc

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ namespace asiodns {
4646

4747
const int DBG_IMPORTANT = DBGLVL_TRACE_BASIC;
4848
const int DBG_COMMON = DBGLVL_TRACE_DETAIL;
49-
const int DBG_ALL = DBGLVL_TRACE_ALL;
49+
const int DBG_VERBOSE = DBGLVL_TRACE_TECHNICAL;
5050

5151
/// @brief IOFetch Data
5252
///
@@ -316,7 +316,7 @@ IOFetch::stop(Result result) {
316316
break;
317317

318318
case SUCCESS:
319-
LOG_DEBUG(logger, DBG_ALL, ASIODNS_FETCH_COMPLETED).
319+
LOG_DEBUG(logger, DBG_VERBOSE, ASIODNS_FETCH_COMPLETED).
320320
arg(data_->remote_rcv->getAddress().toText()).
321321
arg(data_->remote_rcv->getPort());
322322
break;

src/lib/log/log_dbglevels.cc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ extern const int DBGLVL_TRACE_BASIC = 40;
2020
extern const int DBGLVL_TRACE_BASIC_DATA = 45;
2121
extern const int DBGLVL_TRACE_DETAIL = 50;
2222
extern const int DBGLVL_TRACE_DETAIL_DATA = 55;
23-
extern const int DBGLVL_TRACE_ALL = 70;
23+
extern const int DBGLVL_TRACE_TECHNICAL = 70;
24+
extern const int DBGLVL_TRACE_TECHNICAL_DATA = 90;
2425

2526
} // namespace log
2627
} // namespace isc

src/lib/log/log_dbglevels.h

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,11 @@ extern const int DBGLVL_TRACE_DETAIL;
7777
/// @brief Trace data associated with detailed operations.
7878
extern const int DBGLVL_TRACE_DETAIL_DATA;
7979

80-
/// @brief The highest level of debug logging.
81-
extern const int DBGLVL_TRACE_ALL;
80+
/// @brief Trace technical operations.
81+
extern const int DBGLVL_TRACE_TECHNICAL;
82+
83+
/// @brief Trace data associated with technical operations.
84+
extern const int DBGLVL_TRACE_TECHNICAL_DATA;
8285

8386
} // log namespace
8487
} // isc namespace

tools/check-messages.py

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -149,16 +149,22 @@ def check_placeholder_ids(messages):
149149
def generate_page_with_messages_printed_on_each_debug_level(messages, debug_levels):
150150
content = []
151151
for log_level in sorted(set(debug_levels.values())):
152+
messages_at_this_log_level = [(message_id, message) for message_id, message in sorted(messages.items())
153+
if message['debug_log_level_line'] == f'Logged at debug log level {log_level}.']
154+
if len(messages_at_this_log_level) == 0:
155+
# Do not write "Messages printed" subtitle if there are no messages.
156+
continue
152157
subtitle = f'Messages printed on debuglevel {log_level}'
153158
content.append(subtitle)
154159
content.append('=' * len(subtitle))
155160
content.append('\n')
156-
for message_id, message in sorted(messages.items()):
157-
if message['debug_log_level_line'] == f'Logged at debug log level {log_level}.':
158-
content.append(f'- {message_id}')
161+
for message_id, message in messages_at_this_log_level:
162+
content.append(f'- {message_id}')
159163
content.append('\n')
160164
parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
161165
with open(f'{parent_dir}/../doc/sphinx/debug-messages.rst', 'w', encoding='utf-8') as f:
166+
f.write('..\n')
167+
f.write(' File generated by "./tools/check-messages.py -a". Do not edit by hand.\n\n')
162168
for i in content:
163169
f.write(i)
164170
f.write('\n')

0 commit comments

Comments
 (0)