From fd01a8faf77a61fe0680f42c05cde5cfd7be5b92 Mon Sep 17 00:00:00 2001
From: Tomek Mrugalski <tomek@isc.org>
Date: Tue, 22 Jun 2021 20:18:45 +0200
Subject: [PATCH] [#745] Doc update instructions updated

---
 doc/Makefile.am   | 12 ++++++++++++
 doc/devel/doc.dox | 16 ++++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/doc/Makefile.am b/doc/Makefile.am
index b1488c92f2..a359960187 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -75,6 +75,18 @@ nobase_dist_doc_DATA += examples/netconf/comments.json
 nobase_dist_doc_DATA += examples/netconf/simple-dhcp4.json
 nobase_dist_doc_DATA += examples/netconf/simple-dhcp6.json
 
+# If there's any new parameter added for any grammar in one of the daemons, someone should go through
+# this procedure:
+#
+# 1. autoreconf -i && ./configure --enable-generate-docs --enable-generate-parser
+# 2. cd doc
+# 3. make grammar
+# 4. make -C sphinx html
+# 5. Inspect the html output and make sure it's ok.
+# 6. Review changes in doc/sphinx/grammar/*
+# 7. Check in changed files in doc/sphinx/grammar/*
+#
+# Make sure you commit only relevant changes, skip the timestamp only updates.
 grammar:
 if GENERATE_DOCS
 if GENERATE_PARSER
diff --git a/doc/devel/doc.dox b/doc/devel/doc.dox
index 932d0d9ab9..8bfca440dc 100644
--- a/doc/devel/doc.dox
+++ b/doc/devel/doc.dox
@@ -31,6 +31,22 @@ appeared, etc. Those JSON files are loaded by docgen tool that will generate
 api.xml that will be used by make guide. There is no need to generate this,
 unless you alter description of existing commands or add a new one.
 
+Since Kea 1.9.9, this doc has appendix with the grammar. If there were new
+parameters added, you can regenerate the grammars and the appendix with the
+following procedure:
+
+@code
+$ autoreconf -i && ./configure --enable-generate-docs --enable-generate-parser
+$ cd doc
+$ make grammar
+$ make -C sphinx html
+@endcode
+
+After that, inspect the html output and make sure it's ok, review changes in
+\c doc/sphinx/grammar/ and then check in those that are something more than a date
+update. The date is there, so we (and users) can determine if the grammar
+is or isn't out of date.
+
 @section docsNewCommand Documenting new command
 
 There are several steps needed to document a new API command: