[#1240] Fixed template/README

Author: fxdupont

ChangeLog

@@ -1,3 +1,8 @@
+1801.	[doc]		fdupont
+	Moved JSON files describing commands to the share directory
+	and adding a new access entry taking read or write values.
+	(Gitlab #1240)
+
 1800.	[func]		fdupont
 	Added support of basic HTTP authentication in HTTP library,
 	control agent, kea shell and high availability hook.

src/share/api/Makefile.am

@@ -6,7 +6,7 @@ EXTRA_DIST = api_files.mk
 EXTRA_DIST += README
 EXTRA_DIST += _template.json
 EXTRA_DIST += generate-templates
-EXTRA_DIST += cmds-list
+EXTRA_DIST += generate-api-files
 EXTRA_DIST += $(api_files)
 
 install-data-local:

src/share/api/README

@@ -1,27 +1,27 @@
 There are several steps needed to document new API command:
 
-1. edit cmds-list and add the new command
-2. (optional) run: ./generate-templates cmds-list
-   This will go through the list of commands listed in cmds-list
-   and will check if there are corresponding JSON files in api/name.json
+1. (optional) run: ./generate-templates cmd1 cmd2...
+   This will go through the list of commands given in arguments
+   and will check if there are corresponding JSON files in name.json
    If the file is missing, a new JSON will be created using template.
    If you dislike this generator, you can always use _template.json
    and copy it over under the name of a new command.
-3. Edit api/command-name.json. If the command is provided by the daemon
+2. Edit command-name.json. If the command is provided by the daemon
    out of its own (and not via hook), simply delete the hook entry.
    If you don't want to provide command syntax (cmd-syntax key),
    any comments about the syntax (cmd-comment key) or response syntax
    (resp-syntax) or any comment about response (resp-comment), simply
    remove those unused keys. The generator will attempt to generate
    boilerplates for it.
+3. Update api_files.mk. You can also run: ./generate-api-files > api_files.mk
+   or check the update by: ./generate-api-files | diff - api_files.mk
 4. Rebuild User's Guide as usual, run in doc/sphinx folder: make
 
 Files in this directory:
  - README: this file
  - _template.json: template used by generate-templates
  - api-files.mk: list of command files for inclusion in Makefiles
-  (build from 'ls [a-z]*.json > api-files.mk')
- - cmds-list: list of commands, used as the argument of generate-templates
-  (build by 'ls [a-z]*.json | sed 's/\.json//' | sort')
- - generate-templates: script generating a new command file from the
-  command list (cmds-list) and the template (_template.json)
+   (can be build by ./generata-api-files)
+ - generate-templates: script generating new command files from the
+  the template (_template.json)
+ - generate-api-files: script generating api-files.mk

src/share/api/_template.json

@@ -1,4 +1,4 @@
-// Note the api/*.json files are to be processed by api2doc.py and possibly other
+// Note the *.json files are to be processed by api2doc.py and possibly other
 // JSON tools that do not handle comments. If using this template, make sure you
 // have all the comments removed.
 {

src/share/api/cmds-list

@@ -0,0 +1,15 @@
+#!/bin/sh
+
+# This script generates api_files.mk
+# Usage:
+#
+# ./generate-api-files > api_files.mk
+
+if [ $# -ne 0 ]; then
+    echo "Usage: ./generate-api-files"
+    exit
+fi
+
+for f in [a-z]*.json ; do
+    echo "api_files += \$(top_srcdir)/src/share/api/$f"
+done

src/share/api/generate-api-files

@@ -3,23 +3,20 @@
 # This script generates API documentation templates.
 # Usage:
 #
-# ./generate-templates file
+# ./generate-templates cmd...
 #
-# File is expected to have a list of commands, one per line.
-# The templates will be created in api/ directory.
+# Arguments are a list of new commands.
+# The templates will be created in local directory.
 
-if [ $# != 1 ]; then
-    echo "Usage: ./generate-templates file"
-    echo
-    echo "File specifies a plain text file with each line having name of a command"
+if [ $# -eq 0 ]; then
+    echo "Usage: ./generate-templates cmd..."
     exit
 fi
 
-
-mkdir -p api/
-
-while read -r CMD; do
-    F=api/$CMD.json
+while [ $# -ne 0 ]; do
+    CMD="$1"
+    shift
+    F=$CMD.json
 
     if [ -e "$F" ]; then
         echo "$F exists, skipping"
@@ -43,4 +40,4 @@ while read -r CMD; do
     echo "}" >> "$F"
 
     echo "$CMD generated."
-done < "$1"
+done