[#745] Doc update instructions updated

diff --git a/doc/Makefile.am b/doc/Makefile.am
index b1488c92f2f443c67f129bcb504eab78102bfb8b..a3599601870bbcefab1b33b693f3e59609f07e84 100644 (file)
--- 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 932d0d9ab99cbc343a2c669a32032b1a2a008ff6..8bfca440dccc7f3bdcb48a8a4039b71acdfb873b 100644 (file)
--- 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: