[#1945] default to determining list of files automatically in api2doc.py and mes2doc.py

Author: andrei-pavel

doc/sphinx/Makefile.am

@@ -75,8 +75,8 @@ mes-files.txt:
 
 # this rule is only used for development purposes and is not used in official
 # build process as kea-messages.rst is always generated via sphinx's conf.py
-$(srcdir)/kea-messages.rst: $(mes_files) mes2doc.py
-	$(PYTHON) $(srcdir)/mes2doc.py -o $@ $(mes_files)
+$(srcdir)/kea-messages.rst: mes2doc.py
+	$(PYTHON) $(srcdir)/mes2doc.py -o $@
 
 # build the list of api files
 api-files.txt: $(top_srcdir)/src/share/api/api_files.mk
@@ -87,8 +87,8 @@ EXTRA_DIST += mes-files.txt api-files.txt
 
 # this rule is only used for development purposes and is not used in official
 # build process as api.rst is always generated via sphinx's conf.py
-$(srcdir)/api.rst: $(api_files) api-files.txt api2doc.py
-	$(PYTHON) $(srcdir)/api2doc.py -o $@ $(api_files)
+$(srcdir)/api.rst: api2doc.py
+	$(PYTHON) $(srcdir)/api2doc.py -o $@
 
 $(srcdir)/arm/platforms.rst:
 	rm -f $(srcdir)/arm/platforms.rst

doc/sphinx/api2doc.py

@@ -10,16 +10,18 @@
 # - reads *.json files (each file describes a single command)
 # - produces .rst file suitable for Sphinx as output
 
-import os
-import json
 import argparse
 import collections
+import json
+import os
+import pathlib
+import sys
 
 
 def parse_args():
     parser = argparse.ArgumentParser(description='Convert set of *.json files to .rst documentation format')
     parser.add_argument('-o', '--output', help='Output file name (default to stdout).')
-    parser.add_argument('files', help='Input API .json files.', nargs='+')
+    parser.add_argument('files', help='Input API .json files.', nargs='?')
 
     args = parser.parse_args()
     return args
@@ -205,7 +207,14 @@ def generate(in_files, out_file):
 
 def main():
     args = parse_args()
-    generate(args.files, args.output)
+    if args.files is None:
+        parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
+        mes_files = sorted(pathlib.Path(f'{parent_dir}/../..').glob('src/share/api/*.json'))
+        # Convert from Path to str.
+        mes_files = [str(i) for i in mes_files]
+    else:
+        mes_files = args.files
+    generate(mes_files, args.output)
 
 
 if __name__ == '__main__':

doc/sphinx/mes2doc.py

@@ -21,14 +21,16 @@
 # The produced format is ReStructuredText.
 
 import argparse
+import os
 import pathlib
 import re
+import sys
 
 
 def parse_args():
     parser = argparse.ArgumentParser(description='Convert set of *.mes files to .rst documentation format')
     parser.add_argument('-o', '--output', help='Output file name (default to stdout).')
-    parser.add_argument('files', help='Input .mes files.', nargs='+')
+    parser.add_argument('files', help='Input .mes files.', nargs='?')
 
     args = parser.parse_args()
     return args
@@ -116,7 +118,7 @@ def generate_rst(messages):
         rst += '=' * len(msg_id) + '\n'
         rst += '\n'
 
-        rst += '.. code-block::\n'
+        rst += '.. code-block:: text\n'
         rst += '\n'
         rst += '    ' + msg_text + '\n'
         rst += '\n'
@@ -152,7 +154,14 @@ def generate(in_files, out_file):
 
 def main():
     args = parse_args()
-    generate(args.files, args.output)
+    if args.files is None:
+        parent_dir = os.path.dirname(os.path.realpath(os.path.abspath(sys.argv[0])))
+        mes_files = sorted(pathlib.Path(f'{parent_dir}/../..').glob('**/*.mes'))
+        # Convert from Path to str.
+        mes_files = [str(i) for i in mes_files]
+    else:
+        mes_files = args.files
+    generate(mes_files, args.output)
 
 
 if __name__ == '__main__':