[#745] Doc update instructions updated

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

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: