Revision 4b12ab4d055d3c080f93e52f7e5a4b2dec01d30e authored by Dmitri Naumov on 19 May 2021, 09:21:04 UTC, committed by Dmitry Yu. Naumov on 03 June 2021, 16:34:25 UTC
Moving them from protected section. All of the access is now through public interface and these parts can be hidden.
1 parent 69a7f3a
append-xml-tags.py
#!/usr/bin/env python3
# This script augments the parameter documentation pages by information
# such as if they are required/optional, their data typ and in which
# end-to-end tests they are used.
# It uses the cache files generated by normalize-param-cache.py and by
# linked-xml-file.py
# prevent broken pipe error
from signal import signal, SIGPIPE, SIG_DFL
signal(SIGPIPE, SIG_DFL)
import os
import sys
import xml.etree.cElementTree as ET
import json
from print23 import print_
github_src_url = "https://gitlab.opengeosys.org/ogs/ogs/-/tree/master"
github_data_url = "https://gitlab.opengeosys.org/ogs/ogs/-/tree/master/Tests/Data"
if len(sys.argv) != 4:
print_("Usage:")
print_("{0} EXT DATADIR DOCAUXDIR".format(sys.argv[0]))
sys.exit(1)
ext = sys.argv[1]
datadir = sys.argv[2]
docauxdir = sys.argv[3]
extension = "." + ext
datadir = os.path.abspath(datadir)
docauxdir = os.path.abspath(docauxdir)
docdir = os.path.join(docauxdir, "dox", "ProjectFile")
# used to expand documentation entry points to full xml tag paths
# that are used in the prj file.
# For example process on top-level could be expanded to processes.process with
# "process": "processes.process",
#
# See the expansion table in the linked-xml-file.py too.
tag_path_expansion_table = {
"prj": "",
}
# maps tags to additional parameter info obtained prior to this script
dict_tag_info = dict()
def dict_of_list_append(dict_, key, value):
if key in dict_:
dict_[key].append(value)
else:
dict_[key] = [value]
with open(os.path.join(docauxdir, "tested-parameters-cache.json")) as fh:
tested_tags_attrs = json.load(fh)
# read parameter cache (generated by normalize-param-cache.py)
with open(os.path.join(docauxdir, "documented-parameters-cache.txt")) as fh:
for line in fh:
line = line.strip().split("@@@")
if line[0] == "OK":
tagpath = line[3]
dict_of_list_append(dict_tag_info, tagpath, line)
# traverse dox file hierarchy
for (dirpath, _, filenames) in os.walk(docdir):
reldirpath = dirpath[len(docdir) + 1 :]
istag = True
for f in filenames:
if not f.endswith(".dox"):
continue
if f.startswith("i_") or f.startswith("c_"):
tagpath = reldirpath
elif f.startswith("t_"):
tagpath = os.path.join(reldirpath, f[2 : -len(".dox")])
istag = True
elif f.startswith("a_"):
tagpath = os.path.join(reldirpath, f[2 : -len(".dox")])
istag = False
tagpath = tagpath.replace(os.sep, ".")
path = os.path.join(dirpath, f)
with open(path, "a") as fh:
# TODO this can currently only expand the top level
tagpathparts = tagpath.split(".")
if tagpathparts[0] in tag_path_expansion_table:
tagpathparts[0] = tag_path_expansion_table[tagpathparts[0]]
else:
tagpathparts[0] = "NONEXISTENT"
tagpath_expanded = ".".join(tagpathparts).lstrip(".")
if tagpath:
fh.write("\n\n# Additional info\n")
if tagpath in dict_tag_info:
for info in dict_tag_info[tagpath]:
path = info[1]
line = info[2]
fh.write(("\n## From {0} line {1}\n\n").format(path, line))
method = info[6]
if method.endswith("Optional"):
fh.write("- This is an optional parameter.\n")
elif method.endswith("List"):
fh.write(
"- This parameter can be given arbitrarily many times.\n"
)
elif method: # method not empty
fh.write("- This is a required parameter.\n")
datatype = info[5]
if datatype:
fh.write("- Data type: <tt>{0}</tt>\n".format(datatype))
fh.write("- Expanded tag path: {0}\n".format(tagpath_expanded))
fh.write(
"- Go to source code: [→ ogs/ogs/master]({2}/{0}#L{1})\n".format(
path, line, github_src_url
)
)
else:
fh.write("\nNo additional info.\n")
if tagpath_expanded:
fh.write("\n\n# Used in the following test data files\n\n")
try:
datafiles = tested_tags_attrs["tags" if istag else "attributes"][
tagpath
]
for df in sorted(datafiles):
pagename = "ogs_ctest_prj__" + df.replace("/", "__").replace(
".", "__"
)
fh.write(
(
"- \\[[→ ogs/ogs/master]({1}/{0}) | "
+ '\\ref {2} "→ doc"\\] {0}\n'
).format(df, github_data_url, pagename)
)
except KeyError:
fh.write("Used in no end-to-end test cases.\n")
else:
# no additional output for the main doc page
pass
fh.write("\n*/\n")
Computing file changes ...