From: Tomek Mrugalski <tomasz@isc.org>
Date: Tue, 6 Aug 2019 16:19:15 +0000 (+0200)
Subject: [#777,!464] api2doc.py updated to handle new syntax, Makefile.am updated
X-Git-Tag: Kea-1.6.0~41^2~161
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7571271e7a5d8b1b6d7322577ba6258933c0d88e;p=thirdparty%2Fkea.git

[#777,!464] api2doc.py updated to handle new syntax, Makefile.am updated
---

diff --git a/doc/sphinx/Makefile.am b/doc/sphinx/Makefile.am
index 2d838f6c2e..3b3ff5153a 100644
--- a/doc/sphinx/Makefile.am
+++ b/doc/sphinx/Makefile.am
@@ -52,7 +52,7 @@ rst_arm_sources+=arm/netconf.rst
 rst_arm_sources+=arm/quickstart.rst
 rst_arm_sources+=arm/shell.rst
 rst_arm_sources+=arm/stats.rst
-#rst_arm_sources+=$(srcdir)/api.rst TODO: disabled for now
+rst_arm_sources+=$(srcdir)/api.rst
 rst_arm_sources+=$(srcdir)/kea-messages.rst
 
 main_sources=$(rst_arm_sources) conf.py $(static_sources)
@@ -72,8 +72,7 @@ rst_man_sources+=man/perfdhcp.8.rst
 man_sources=$(rst_man_sources) conf.py
 man8s=$(foreach rst,$(rst_man_sources), $(sphinxbuilddir)/$(basename $(rst)))
 
-EXTRA_DIST += $(main_sources) $(man_sources) mes2doc.py  # api2doc.py
-
+EXTRA_DIST += $(main_sources) $(man_sources) mes2doc.py api2doc.py
 
 # list of messages files that are used to generate kea-messages.rst and then kea-messages.pdf
 mes_files=
@@ -228,8 +227,7 @@ api_files+=$(srcdir)/api/subnet6-list.json
 api_files+=$(srcdir)/api/subnet6-update.json
 api_files+=$(srcdir)/api/version-get.json
 
-#EXTRA_DIST += $(api_files)
-
+EXTRA_DIST += $(api_files)
 
 if HAVE_PDFLATEX
 all: html mans pdf
@@ -241,8 +239,8 @@ $(srcdir)/kea-messages.rst: $(mes_files) mes2doc.py
 	$(PYTHON) $(srcdir)/mes2doc.py -o $@ $(mes_files)
 
 
-#$(srcdir)/api.rst: $(api_files) api2doc.py
-#	$(PYTHON) $(srcdir)/api2doc.py -o $@ $(api_files)
+$(srcdir)/api.rst: $(api_files) api2doc.py
+	$(PYTHON) $(srcdir)/api2doc.py -o $@ $(api_files)
 
 
 PDFLATEX_AND_OPTS=$(PDFLATEX) -interaction nonstopmode
@@ -265,6 +263,9 @@ pdf: $(main_sources)
 html: $(main_sources)
 	$(SPHINXBUILD) -M html $(srcdir) $(sphinxbuilddir) $(sphinxopts)
 
+singlehtml: $(main_sources)
+	$(SPHINXBUILD) -M singlehtml $(srcdir) $(sphinxbuilddir) $(sphinxopts)
+
 $(man8s): mans
 
 mans: $(man_sources)
diff --git a/doc/sphinx/api2doc.py b/doc/sphinx/api2doc.py
index 60ed6e951c..3c5f17040c 100755
--- a/doc/sphinx/api2doc.py
+++ b/doc/sphinx/api2doc.py
@@ -6,7 +6,9 @@
 # License, v. 2.0. If a copy of the MPL was not distributed with this
 # file, You can obtain one at http:#mozilla.org/MPL/2.0/.
 
-# Produce API Manual
+# Produce API Reference
+# - reads *.json files (each file describes a single command)
+# - produces .rst file suitable for Sphinx as output
 
 import os
 import json
@@ -27,7 +29,12 @@ def read_input_files(files):
     apis = {}
     for f in files:
         name = os.path.basename(f)[:-5]
+        # Skip special names starting with _ (such as _template.json)
+        if name[:1] == '_':
+            print("Skipping %s (starts with underscore)" % f)
+            continue
         with open(f) as fp:
+            print("Processing %s" % f)
             # use OrderedDict to preserve order of fields in cmd-syntax
             try:
                 descr = json.load(fp, object_pairs_hook=collections.OrderedDict)
@@ -87,7 +94,9 @@ API Reference
         rst += '-' * len(name) + '\n\n'
 
         # command overview
-        rst += '%s\n\n' % func['brief']
+        for brief_line in func['brief']:
+            rst += '%s\n' % brief_line
+        rst += '\n'
 
         # command can be issued to the following daemons
         rst += 'Supported by: '
@@ -104,7 +113,7 @@ API Reference
 
         # command syntax
         rst += 'Command syntax:\n\n'
-        rst += '.. code-block:: json\n\n'
+        rst += '.. code-block:: \n\n'
         if 'cmd-syntax' in func:
             cmd_syntaxes = [func['cmd-syntax']]
             if isinstance(cmd_syntaxes, dict):
@@ -114,9 +123,9 @@ API Reference
                     rst += cmd_syntax['comment']
                     rst += '\n\n'
                     del cmd_syntax['comment']
-                txt = json.dumps(cmd_syntax, indent=4, separators=(',', ': '))
-                lines = [ '    %s' % l for l in txt.splitlines()]
-                rst += '\n'.join(lines)
+
+                for line in cmd_syntax:
+                    rst += '    %s\n' % line
         else:
             rst += '   {\n'
             rst += '       "command": \"%s\"\n' % name
@@ -124,20 +133,25 @@ API Reference
         rst += '\n\n'
 
         if 'cmd-comment' in func:
-            rst += func['cmd-comment']
-            rst += '\n\n'
+            for l in func['cmd-comment']:
+                rst += "%s\n" % l
+            rst += '\n'
 
         # response syntax
         rst += 'Response syntax:\n\n'
-        rst += '.. code-block:: json\n\n'
+        rst += '.. code-block:: \n\n'
         if 'resp-syntax' in func:
             resp_syntaxes = [func['resp-syntax']]
             if isinstance(resp_syntaxes, dict):
                 resp_syntaxes = [resp_syntax]
             for resp_syntax in resp_syntaxes:
-                txt = json.dumps(resp_syntax, indent=4, separators=(',', ': '))
-                lines = [ '    %s' % l for l in txt.splitlines()]
-                rst += '\n'.join(lines)
+
+                for line in resp_syntax:
+                    rst += '    %s\n' % line
+
+                #txt = json.dumps(resp_syntax, indent=4, separators=(',', ': '))
+                #lines = [ '    %s' % l for l in txt.splitlines()]
+                #rst += '\n'.join(lines)
         else:
             rst += '   {\n'
             rst += '       "result": "<integer>",\n'
@@ -146,7 +160,8 @@ API Reference
         rst += '\n\n'
 
         if 'resp-comment' in func:
-            rst += func['resp-comment']
+            for resp_comment_line in func['resp-comment']:
+                rst += "%s\n" % resp_comment_line
             rst += '\n\n'
         else:
             rst += 'Result is an integer representation of the status. Currently supported statuses are:\n\n'