mir/kea
2
0
Fork 0
mirror of https://gitlab.isc.org/isc-projects/kea synced 2025-09-03 07:25:18 +00:00
Code Issues Releases Wiki Activity

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

Browse Source
This commit is contained in:
Andrei Pavel
2024-08-19 19:06:41 +03:00
parent a56fb8d6c6
commit 49392bf857
3 changed files with 29 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
doc/sphinx/Makefile.am
View File

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

17
doc/sphinx/api2doc.py
View File

@@ -10,16 +10,18 @@
# - reads *.json files (each file describes a single command) # - reads *.json files (each file describes a single command)
# - produces .rst file suitable for Sphinx as output # - produces .rst file suitable for Sphinx as output
import os
import json
import argparse import argparse
import collections import collections
import json
import os
import pathlib
import sys
def parse_args(): def parse_args():
parser = argparse.ArgumentParser(description='Convert set of *.json files to .rst documentation format') 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('-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() args = parser.parse_args()
return args return args
@@ -205,7 +207,14 @@ def generate(in_files, out_file):
def main(): def main():
args = parse_args() 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__': if __name__ == '__main__':

15
doc/sphinx/mes2doc.py
View File

@@ -21,14 +21,16 @@
# The produced format is ReStructuredText. # The produced format is ReStructuredText.
import argparse import argparse
import os
import pathlib import pathlib
import re import re
import sys
def parse_args(): def parse_args():
parser = argparse.ArgumentParser(description='Convert set of *.mes files to .rst documentation format') 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('-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() args = parser.parse_args()
return args return args
@@ -116,7 +118,7 @@ used to indicate a placeholder for data that is provided by the Kea code during
rst += '=' * len(msg_id) + '\n' rst += '=' * len(msg_id) + '\n'
rst += '\n' rst += '\n'
rst += '.. code-block::\n' rst += '.. code-block:: text\n'
rst += '\n' rst += '\n'
rst += ' ' + msg_text + '\n' rst += ' ' + msg_text + '\n'
rst += '\n' rst += '\n'
@@ -152,7 +154,14 @@ def generate(in_files, out_file):
def main(): def main():
args = parse_args() 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__': if __name__ == '__main__':