From: Michal Nowikowski Date: Thu, 18 Jul 2019 12:37:52 +0000 (+0200) Subject: revamped api doc generation X-Git-Tag: Kea-1.6.1~10^2~62 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=519035a179c04f8bedca006a141e0af8b224f8ac;p=thirdparty%2Fkea.git revamped api doc generation --- diff --git a/doc/sphinx/.gitignore b/doc/sphinx/.gitignore index 183ae1dd8b..ce7f2dce0e 100644 --- a/doc/sphinx/.gitignore +++ b/doc/sphinx/.gitignore @@ -1,3 +1,4 @@ /_build +/api.rst /kea-messages.rst diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am index 6fd6f8874e..92b7ed1403 100644 --- a/doc/sphinx/Makefile.am +++ b/doc/sphinx/Makefile.am @@ -23,7 +23,6 @@ static_sources+=static/kea.css rst_arm_sources= rst_arm_sources+=arm/admin.rst rst_arm_sources+=arm/agent.rst -rst_arm_sources+=arm/api.rst rst_arm_sources+=arm/classify.rst rst_arm_sources+=arm/config-backend.rst rst_arm_sources+=arm/config.rst @@ -42,7 +41,7 @@ rst_arm_sources+=arm/hooks-radius.rst rst_arm_sources+=arm/hooks.rst rst_arm_sources+=arm/hooks-stat-cmds.rst rst_arm_sources+=arm/install.rst -rst_arm_sources+=arm/index.rst +rst_arm_sources+=index.rst rst_arm_sources+=arm/intro.rst rst_arm_sources+=arm/keactrl.rst rst_arm_sources+=arm/lease-expiration.rst @@ -74,10 +73,10 @@ endif man_sources=$(rst_man_sources) conf.py man8s=$(foreach rst,$(rst_man_sources), $(sphinxbuilddir)/$(basename $(rst))) -EXTRA_DIST += $(main_sources) $(man_sources) system_messages.py +EXTRA_DIST += $(main_sources) $(man_sources) mes2doc.py -# list of messages files that are used to generate kea-messages.pdf +# list of messages files that are used to generate kea-messages.rst and then kea-messages.pdf mes_files= mes_files+=$(top_srcdir)/src/hooks/dhcp/mysql_cb/mysql_cb_messages.mes mes_files+=$(top_srcdir)/src/hooks/dhcp/lease_cmds/lease_cmds_messages.mes @@ -107,17 +106,147 @@ if HAVE_SYSREPO mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes endif +# list of api files that are used to generate api.rst +api_files= +api_files+=api/build-report.json +api_files+=api/cache-clear.json +api_files+=api/cache-get.json +api_files+=api/cache-get-by-id.json +api_files+=api/cache-insert.json +api_files+=api/cache-load.json +api_files+=api/cache-remove.json +api_files+=api/cache-size.json +api_files+=api/cache-write.json +api_files+=api/class-add.json +api_files+=api/class-del.json +api_files+=api/class-get.json +api_files+=api/class-list.json +api_files+=api/class-update.json +api_files+=api/config-get.json +api_files+=api/config-reload.json +api_files+=api/config-set.json +api_files+=api/config-test.json +api_files+=api/config-write.json +api_files+=api/dhcp-disable.json +api_files+=api/dhcp-enable.json +api_files+=api/ha-continue.json +api_files+=api/ha-heartbeat.json +api_files+=api/ha-scopes.json +api_files+=api/ha-sync.json +api_files+=api/lease4-add.json +api_files+=api/lease4-del.json +api_files+=api/lease4-get-all.json +api_files+=api/lease4-get.json +api_files+=api/lease4-update.json +api_files+=api/lease4-wipe.json +api_files+=api/lease6-add.json +api_files+=api/lease6-del.json +api_files+=api/lease6-get-all.json +api_files+=api/lease6-get.json +api_files+=api/lease6-update.json +api_files+=api/lease6-wipe.json +api_files+=api/leases-reclaim.json +api_files+=api/libreload.json +api_files+=api/list-commands.json +api_files+=api/network4-add.json +api_files+=api/network4-del.json +api_files+=api/network4-get.json +api_files+=api/network4-list.json +api_files+=api/network4-subnet-add.json +api_files+=api/network4-subnet-del.json +api_files+=api/network6-add.json +api_files+=api/network6-del.json +api_files+=api/network6-get.json +api_files+=api/network6-list.json +api_files+=api/network6-subnet-add.json +api_files+=api/network6-subnet-del.json +api_files+=api/remote-global-parameter4-del.json +api_files+=api/remote-global-parameter4-get-all.json +api_files+=api/remote-global-parameter4-get.json +api_files+=api/remote-global-parameter4-set.json +api_files+=api/remote-global-parameter6-del.json +api_files+=api/remote-global-parameter6-get-all.json +api_files+=api/remote-global-parameter6-get.json +api_files+=api/remote-global-parameter6-set.json +api_files+=api/remote-network4-del.json +api_files+=api/remote-network4-get.json +api_files+=api/remote-network4-list.json +api_files+=api/remote-network4-set.json +api_files+=api/remote-network6-del.json +api_files+=api/remote-network6-get.json +api_files+=api/remote-network6-list.json +api_files+=api/remote-network6-set.json +api_files+=api/remote-option-def4-del.json +api_files+=api/remote-option-def4-get-all.json +api_files+=api/remote-option-def4-get.json +api_files+=api/remote-option-def4-set.json +api_files+=api/remote-option-def6-del.json +api_files+=api/remote-option-def6-get-all.json +api_files+=api/remote-option-def6-get.json +api_files+=api/remote-option-def6-set.json +api_files+=api/remote-option4-global-del.json +api_files+=api/remote-option4-global-get-all.json +api_files+=api/remote-option4-global-get.json +api_files+=api/remote-option4-global-set.json +api_files+=api/remote-option6-global-del.json +api_files+=api/remote-option6-global-get-all.json +api_files+=api/remote-option6-global-get.json +api_files+=api/remote-option6-global-set.json +api_files+=api/remote-subnet4-del-by-id.json +api_files+=api/remote-subnet4-del-by-prefix.json +api_files+=api/remote-subnet4-get-by-id.json +api_files+=api/remote-subnet4-get-by-prefix.json +api_files+=api/remote-subnet4-list.json +api_files+=api/remote-subnet4-set.json +api_files+=api/remote-subnet6-del-by-id.json +api_files+=api/remote-subnet6-del-by-prefix.json +api_files+=api/remote-subnet6-get-by-id.json +api_files+=api/remote-subnet6-get-by-prefix.json +api_files+=api/remote-subnet6-list.json +api_files+=api/remote-subnet6-set.json +api_files+=api/reservation-add.json +api_files+=api/reservation-del.json +api_files+=api/reservation-get.json +api_files+=api/reservation-get-all.json +api_files+=api/reservation-get-page.json +api_files+=api/shutdown.json +api_files+=api/statistic-get-all.json +api_files+=api/statistic-get.json +api_files+=api/statistic-remove-all.json +api_files+=api/statistic-remove.json +api_files+=api/statistic-reset-all.json +api_files+=api/statistic-reset.json +api_files+=api/stat-lease4-get.json +api_files+=api/stat-lease6-get.json +api_files+=api/subnet4-add.json +api_files+=api/subnet4-del.json +api_files+=api/subnet4-get.json +api_files+=api/subnet4-list.json +api_files+=api/subnet4-update.json +api_files+=api/subnet6-add.json +api_files+=api/subnet6-del.json +api_files+=api/subnet6-get.json +api_files+=api/subnet6-list.json +api_files+=api/subnet6-update.json +api_files+=api/version-get.json + +EXTRA_DIST += $(api_files) + all: html mans pdf -kea-messages.rst: $(mes_files) system_messages.py - $(srcdir)/system_messages.py -o $@ $(mes_files) +kea-messages.rst: $(mes_files) mes2doc.py + $(srcdir)/mes2doc.py -o $@ $(mes_files) + +api.rst: $(api_files) api2doc.py + $(srcdir)/api2doc.py -o $@ $(api_files) -pdf: $(main_sources) kea-messages.rst + +pdf: $(main_sources) api.rst kea-messages.rst $(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts) -html: $(main_sources) kea-messages.rst +html: $(main_sources) api.rst kea-messages.rst $(SPHINXBUILD) -M html $(srcdir) $(sphinxbuilddir) $(sphinxopts) $(man8s): mans @@ -138,7 +267,7 @@ uninstall-local: clean-local: rm -rf $(sphinxbuilddir) - rm -f kea-messages.rst + rm -f api.rst kea-messages.rst .PHONY: all pdf html mans @@ -182,93 +311,3 @@ api: docgen # This convenience target makes sure the docgen tool is built properly docgen: $(MAKE) -C docgen - - -# These are files that document our APIs. They're not really needed as the -# content is included in the api.xml, but may be useful for people who -# want to document the API. -EXTRA_DIST += api/build-report.json -EXTRA_DIST += api/cache-clear.json api/cache-get.json -EXTRA_DIST += api/cache-get-by-id.json api/cache-insert.json -EXTRA_DIST += api/cache-load.json api/cache-remove.json -EXTRA_DIST += api/cache-size.json api/cache-write.json -EXTRA_DIST += api/class-add.json api/class-del.json -EXTRA_DIST += api/class-get.json api/class-list.json -EXTRA_DIST += api/class-update.json -EXTRA_DIST += api/config-get.json api/config-reload.json -EXTRA_DIST += api/config-set.json api/config-test.json -EXTRA_DIST += api/config-write.json api/dhcp-disable.json -EXTRA_DIST += api/dhcp-enable.json api/ha-continue.json -EXTRA_DIST += api/ha-heartbeat.json api/ha-scopes.json -EXTRA_DIST += api/ha-sync.json api/lease4-add.json -EXTRA_DIST += api/lease4-del.json api/lease4-get-all.json -EXTRA_DIST += api/lease4-get.json api/lease4-update.json -EXTRA_DIST += api/lease4-wipe.json api/lease6-add.json -EXTRA_DIST += api/lease6-del.json api/lease6-get-all.json -EXTRA_DIST += api/lease6-get.json api/lease6-update.json -EXTRA_DIST += api/lease6-wipe.json api/leases-reclaim.json -EXTRA_DIST += api/libreload.json api/list-commands.json -EXTRA_DIST += api/network4-add.json api/network4-del.json -EXTRA_DIST += api/network4-get.json api/network4-list.json -EXTRA_DIST += api/network4-subnet-add.json api/network4-subnet-del.json -EXTRA_DIST += api/network6-add.json api/network6-del.json -EXTRA_DIST += api/network6-get.json api/network6-list.json -EXTRA_DIST += api/network6-subnet-add.json api/network6-subnet-del.json -EXTRA_DIST += api/remote-global-parameter4-del.json -EXTRA_DIST += api/remote-global-parameter4-get-all.json -EXTRA_DIST += api/remote-global-parameter4-get.json -EXTRA_DIST += api/remote-global-parameter4-set.json -EXTRA_DIST += api/remote-global-parameter6-del.json -EXTRA_DIST += api/remote-global-parameter6-get-all.json -EXTRA_DIST += api/remote-global-parameter6-get.json -EXTRA_DIST += api/remote-global-parameter6-set.json -EXTRA_DIST += api/remote-network4-del.json -EXTRA_DIST += api/remote-network4-get.json -EXTRA_DIST += api/remote-network4-list.json -EXTRA_DIST += api/remote-network4-set.json -EXTRA_DIST += api/remote-network6-del.json -EXTRA_DIST += api/remote-network6-get.json -EXTRA_DIST += api/remote-network6-list.json -EXTRA_DIST += api/remote-network6-set.json -EXTRA_DIST += api/remote-option-def4-del.json -EXTRA_DIST += api/remote-option-def4-get-all.json -EXTRA_DIST += api/remote-option-def4-get.json -EXTRA_DIST += api/remote-option-def4-set.json -EXTRA_DIST += api/remote-option-def6-del.json -EXTRA_DIST += api/remote-option-def6-get-all.json -EXTRA_DIST += api/remote-option-def6-get.json -EXTRA_DIST += api/remote-option-def6-set.json -EXTRA_DIST += api/remote-option4-global-del.json -EXTRA_DIST += api/remote-option4-global-get-all.json -EXTRA_DIST += api/remote-option4-global-get.json -EXTRA_DIST += api/remote-option4-global-set.json -EXTRA_DIST += api/remote-option6-global-del.json -EXTRA_DIST += api/remote-option6-global-get-all.json -EXTRA_DIST += api/remote-option6-global-get.json -EXTRA_DIST += api/remote-option6-global-set.json -EXTRA_DIST += api/remote-subnet4-del-by-id.json -EXTRA_DIST += api/remote-subnet4-del-by-prefix.json -EXTRA_DIST += api/remote-subnet4-get-by-id.json -EXTRA_DIST += api/remote-subnet4-get-by-prefix.json -EXTRA_DIST += api/remote-subnet4-list.json -EXTRA_DIST += api/remote-subnet4-set.json -EXTRA_DIST += api/remote-subnet6-del-by-id.json -EXTRA_DIST += api/remote-subnet6-del-by-prefix.json -EXTRA_DIST += api/remote-subnet6-get-by-id.json -EXTRA_DIST += api/remote-subnet6-get-by-prefix.json -EXTRA_DIST += api/remote-subnet6-list.json -EXTRA_DIST += api/remote-subnet6-set.json -EXTRA_DIST += api/reservation-add.json api/reservation-del.json -EXTRA_DIST += api/reservation-get.json api/reservation-get-all.json -EXTRA_DIST += api/reservation-get-page.json api/shutdown.json -EXTRA_DIST += api/statistic-get-all.json api/statistic-get.json -EXTRA_DIST += api/statistic-remove-all.json api/statistic-remove.json -EXTRA_DIST += api/statistic-reset-all.json api/statistic-reset.json -EXTRA_DIST += api/stat-lease4-get.json api/stat-lease6-get.json -EXTRA_DIST += api/subnet4-add.json api/subnet4-del.json -EXTRA_DIST += api/subnet4-get.json api/subnet4-list.json -EXTRA_DIST += api/subnet4-update.json -EXTRA_DIST += api/subnet6-add.json api/subnet6-del.json -EXTRA_DIST += api/subnet6-get.json api/subnet6-list.json -EXTRA_DIST += api/subnet6-update.json -EXTRA_DIST += api/_template.json api/version-get.json diff --git a/doc/sphinx/api/build-report.json b/doc/sphinx/api/build-report.json index 10b62fb610..8a48890dc1 100644 --- a/doc/sphinx/api/build-report.json +++ b/doc/sphinx/api/build-report.json @@ -3,14 +3,8 @@ "brief": "Returns a list of compilation options that this particular binary was built with", "support": [ "kea-dhcp4", "kea-dhcp6", "kea-dhcp-ddns", "kea-ctrl-agent" ], "avail": "1.2.0", - - "cmd-syntax": "{ - \"command\": \"build-report\" -}", - - "resp-syntax": "{ - \"result\": 0, - \"text\": -}", - "resp-comment": "" + "resp-syntax": { + "result": 0, + "text": "" + } } diff --git a/doc/sphinx/api/cache-get-by-id.json b/doc/sphinx/api/cache-get-by-id.json index ec7fd55826..dbabce36ef 100644 --- a/doc/sphinx/api/cache-get-by-id.json +++ b/doc/sphinx/api/cache-get-by-id.json @@ -4,14 +4,15 @@ "support": [ "kea-dhcp4", "kea-dhcp6" ], "avail": "1.6.0", "hook": "host_cache", - "cmd-syntax": "{ - \"command\": \"cache-get-by-id\", - \"arguments\": { - \"hw-address\": \"01:02:03:04:05:06\" - }", - "resp-syntax": "{ - \"result\": 0 - \"text\": \"2 entries returned.\" - \"arguments\": -}" + "cmd-syntax": { + "command": "cache-get-by-id", + "arguments": { + "hw-address": "01:02:03:04:05:06" + } + }, + "resp-syntax": { + "result": 0, + "text": "2 entries returned.", + "arguments": "" + } } diff --git a/doc/sphinx/api/cache-get.json b/doc/sphinx/api/cache-get.json index 7c72ff1b7f..98458d09b1 100644 --- a/doc/sphinx/api/cache-get.json +++ b/doc/sphinx/api/cache-get.json @@ -5,9 +5,9 @@ "avail": "1.4.0", "hook": "host_cache", - "resp-syntax": "{ - \"result\": 0 - \"text\": \"123 entries returned.\" - \"arguments\": -}" + "resp-syntax": { + "result": 0, + "text": "123 entries returned.", + "arguments": "" + } } diff --git a/doc/sphinx/api/cache-insert.json b/doc/sphinx/api/cache-insert.json index e872c9ae04..d4fa0f9b10 100644 --- a/doc/sphinx/api/cache-insert.json +++ b/doc/sphinx/api/cache-insert.json @@ -5,41 +5,40 @@ "support": [ "kea-dhcp4", "kea-dhcp6" ], "avail": "1.4.0", "hook": "host_cache", - "cmd-syntax": "{ - \"command\": \"cache-insert\", - \"arguments\": { - \"hw-address\": \"01:02:03:04:05:06\", - \"subnet-id4\": 4, - \"subnet-id6\": 0, - \"ip-address\": \"192.0.2.100\", - \"hostname\": \"somehost.example.org\", - \"client-classes4\": [ ], - \"client-classes6\": [ ], - \"option-data4\": [ ], - \"option-data6\": [ ], - \"next-server\": \"192.0.0.2\", - \"server-hostname\": \"server-hostname.example.org\", - \"boot-file-name\": \"bootfile.efi\", - \"host-id\": 0 - } -}, -{ - \"command\": \"cache-insert\", - \"arguments\": { - \"hw-address\": \"01:02:03:04:05:06\", - \"subnet-id4\": 0, - \"subnet-id6\": 6, - \"ip-addresses\": [ \"2001:db8::cafe:babe\" ], - \"prefixes\": [ \"2001:db8:dead:beef::/64\" ], - \"hostname\": \"\", - \"client-classes4\": [ ], - \"client-classes6\": [ ], - \"option-data4\": [ ], - \"option-data6\": [ ], - \"next-server\": \"0.0.0.0\", - \"server-hostname\": \"\", - \"boot-file-name\": \"\", - \"host-id\": 0 - } -}" + "cmd-syntax": [{ + "command": "cache-insert", + "arguments": { + "hw-address": "01:02:03:04:05:06", + "subnet-id4": 4, + "subnet-id6": 0, + "ip-address": "192.0.2.100", + "hostname": "somehost.example.org", + "client-classes4": [ ], + "client-classes6": [ ], + "option-data4": [ ], + "option-data6": [ ], + "next-server": "192.0.0.2", + "server-hostname": "server-hostname.example.org", + "boot-file-name": "bootfile.efi", + "host-id": 0 + } + }, { + "command": "cache-insert", + "arguments": { + "hw-address": "01:02:03:04:05:06", + "subnet-id4": 0, + "subnet-id6": 6, + "ip-addresses": [ "2001:db8::cafe:babe" ], + "prefixes": [ "2001:db8:dead:beef::/64" ], + "hostname": "", + "client-classes4": [ ], + "client-classes6": [ ], + "option-data4": [ ], + "option-data6": [ ], + "next-server": "0.0.0.0", + "server-hostname": "", + "boot-file-name": "", + "host-id": 0 + } + }] } diff --git a/doc/sphinx/api/cache-load.json b/doc/sphinx/api/cache-load.json index 582dc11b86..c49c2bad42 100644 --- a/doc/sphinx/api/cache-load.json +++ b/doc/sphinx/api/cache-load.json @@ -5,8 +5,8 @@ "support": [ "kea-dhcp4", "kea-dhcp6" ], "avail": "1.4.0", "hook": "host_cache", - "cmd-syntax": "{ - \"command\": \"cache-load\", - \"arguments\": \"/tmp/kea-host-cache.json\" -}" + "cmd-syntax": { + "command": "cache-load", + "arguments": "/tmp/kea-host-cache.json" + } } diff --git a/doc/sphinx/api/cache-remove.json b/doc/sphinx/api/cache-remove.json index 564a28ec56..ac933b4fb3 100644 --- a/doc/sphinx/api/cache-remove.json +++ b/doc/sphinx/api/cache-remove.json @@ -5,20 +5,18 @@ "support": [ "kea-dhcp4", "kea-dhcp6" ], "avail": "1.4.0", "hook": "host_cache", - "cmd-syntax": "{ - \"command\": \"cache-remove\", - \"arguments\": { - \"ip-address\": \"192.0.2.1\", - \"subnet-id\": 123 - } -} - -Another example that removes IPv6 host identifier by DUID and specific subnet-id is: -{ - \"command\": \"cache-remove\", - \"arguments\": { - \"duid\": \"00:01:ab:cd:f0:a1:c2:d3:e4\", - \"subnet-id\": 123 - } -}" + "cmd-syntax": [{ + "command": "cache-remove", + "arguments": { + "ip-address": "192.0.2.1", + "subnet-id": 123 + } + }, { + "command": "cache-remove", + "arguments": { + "duid": "00:01:ab:cd:f0:a1:c2:d3:e4", + "subnet-id": 123 + }, + "comment": "Another example that removes IPv6 host identifier by DUID and specific subnet-id is:" + }] } diff --git a/doc/sphinx/api/cache-size.json b/doc/sphinx/api/cache-size.json index d30f9daa38..d197c979a9 100644 --- a/doc/sphinx/api/cache-size.json +++ b/doc/sphinx/api/cache-size.json @@ -5,9 +5,9 @@ "avail": "1.6.0", "hook": "host_cache", - "resp-syntax": "{ - \"result\": 0 - \"text\": \"123 entries.\" - \"arguments\": { \"size\": 123 } -}" + "resp-syntax": { + "result": 0, + "text": "123 entries.", + "arguments": { "size": 123 } + } } diff --git a/doc/sphinx/api/cache-write.json b/doc/sphinx/api/cache-write.json index 635fe666e7..a223adafe7 100644 --- a/doc/sphinx/api/cache-write.json +++ b/doc/sphinx/api/cache-write.json @@ -5,9 +5,9 @@ "avail": "1.4.0", "hook": "host_cache", - "cmd-syntax": "{ - \"command\": \"cache-write\", - \"arguments\": \"/path/to/the/file.json\" -}", + "cmd-syntax": { + "command": "cache-write", + "arguments": "/path/to/the/file.json" + }, "cmd-comment": "The command takes one mandatory argument that specifies a filename path of a file to be written." } diff --git a/doc/sphinx/api/class-add.json b/doc/sphinx/api/class-add.json index 69e9a47900..c9e19d3c0c 100644 --- a/doc/sphinx/api/class-add.json +++ b/doc/sphinx/api/class-add.json @@ -1,33 +1,28 @@ { "name": "class-add", - "brief": "This command is used to create and add a new class to the existing - server configuration.", + "brief": "This command is used to create and add a new class to the existing server configuration.", "description": "See ", "support": [ "kea-dhcp4", "kea-dhcp6" ], "avail": "1.5.0", "hook": "class_cmds", - "cmd-syntax": "{ - \"command\": \"class-add\", - \"arguments\": { - \"client-classes\": [ { - \"name\": , - \"test\": , - \"option-data\": [