Skip to content

Commit f82f933

Browse files
lostbardlostbard
committed
docs: update doc generation
* Makefile: update texinfo rule for copy links * doc/mkqhcp.py, doc/mkfuncdocs.py: latest scripts
1 parent 1d170fc commit f82f933

File tree

3 files changed

+94
-13
lines changed

3 files changed

+94
-13
lines changed

‎Makefile‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ CUT ?= cut
1515
TR ?= tr
1616
TEXI2PDF ?= texi2pdf -q
1717
MAKEINFO ?= makeinfo
18+
MAKEINFO_HTML_OPTIONS := --no-headers --set-customization-variable 'COPIABLE_LINKS 0' --set-customization-variable 'COPIABLE_ANCHORS 0' --no-split
1819

1920
# work out a possible help generator
2021
ifeq ($(strip $(QHELPGENERATOR)),)
@@ -288,7 +289,7 @@ doc/$(packageprefix)$(package).pdf: doc/$(packageprefix)$(package).texi doc/func
288289
cd doc && $(RM) -f $(packageprefix)$(package).aux $(packageprefix)$(package).cp $(packageprefix)$(package).cps $(packageprefix)$(package).fn $(packageprefix)$(package).fns $(packageprefix)$(package).log $(packageprefix)$(package).toc
289290

290291
doc/$(packageprefix)$(package).html: doc/$(packageprefix)$(package).texi doc/functions.texi doc/version.texi
291-
cd doc && SOURCE_DATE_EPOCH=$(REPO_TIMESTAMP) $(MAKEINFO) --html --css-ref=$(packageprefix)$(package).css --no-split --output=$(packageprefix)${package}.html $(packageprefix)$(package).texi
292+
cd doc && SOURCE_DATE_EPOCH=$(REPO_TIMESTAMP) $(MAKEINFO) --html --css-ref=$(packageprefix)$(package).css $(MAKEINFO_HTML_OPTIONS) --output=$(packageprefix)${package}.html $(packageprefix)$(package).texi
292293

293294
doc/functions.texi: $(release_dir_dep)
294295
cd doc && ./mkfuncdocs.py --src-dir=../inst/ ../INDEX | $(SED) 's/@seealso/@xseealso/g' > functions.texi

‎doc/mkfuncdocs.py‎

Lines changed: 70 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
#!/usr/bin/python3
22

3-
## Copyright 2018-2023 John Donoghue
3+
## Copyright 2018-2024 John Donoghue
44
##
55
## This program is free software: you can redistribute it and/or modify it
66
## under the terms of the GNU General Public License as published by
@@ -16,7 +16,7 @@
1616
## along with this program. If not, see
1717
## <https://www.gnu.org/licenses/>.
1818

19-
## mkfuncdocs v1.0.7
19+
## mkfuncdocs v1.0.8
2020
## mkfuncdocs.py will attempt to extract the help texts from functions in src
2121
## dirs, extracting only those that are in the specifed INDEX file and output them
2222
## to stdout in texi format
@@ -89,6 +89,36 @@ def find_defun_line_in_file(filename, fnname):
8989

9090
return -1
9191

92+
def find_function_line_in_file(filename, fnname):
93+
linecnt = 0
94+
func = False
95+
defun_line=re.compile(r"^\s*function \s*")
96+
with open(filename, 'rt') as f:
97+
for line in f:
98+
if func == True:
99+
x = line.strip()
100+
if x.startswith("## -*- texinfo -*-"):
101+
return linecnt
102+
else:
103+
func = False
104+
105+
if re.match(defun_line, line):
106+
if line.find("=") != -1:
107+
x = line.split("=")
108+
x = x[-1]
109+
else:
110+
x = line.replace("function ", "")
111+
112+
x = x.split("(")
113+
x = x[0].strip()
114+
if x == fnname:
115+
func = True
116+
117+
linecnt = linecnt + 1
118+
119+
return -1
120+
121+
92122
def read_m_file(filename, skip=0):
93123
help = []
94124
inhelp = False
@@ -195,6 +225,29 @@ def read_index (filename, ignore):
195225

196226
return index;
197227

228+
def find_class_file(fname, paths):
229+
230+
for f in paths:
231+
# class constructor ?
232+
name = f + "/@" + fname + "/" + fname + ".m"
233+
if os.path.isfile(name):
234+
return name, 0
235+
236+
# perhaps classname.func format ?
237+
x = fname.split(".")
238+
if len(x) > 0:
239+
zname = x.pop()
240+
cname = ".".join(x)
241+
name = f + "/" + cname + ".m"
242+
if os.path.isfile(name):
243+
idx = find_function_line_in_file(name, zname)
244+
if idx >= 0:
245+
return name, idx
246+
name = f + "/@" + cname + "/" + zname + ".m"
247+
if os.path.isfile(name):
248+
return name, 0
249+
return None, -1
250+
198251
def find_func_file(fname, paths, prefix, scanfiles=False):
199252
for f in paths:
200253
name = f + "/" + fname + ".m"
@@ -205,7 +258,6 @@ def find_func_file(fname, paths, prefix, scanfiles=False):
205258
if os.path.isfile(name):
206259
return name, 0
207260
name = f + "/" + fname + ".cc"
208-
name = f + "/" + fname + ".cc"
209261
if os.path.isfile(name):
210262
return name, 0
211263
name = f + "/" + fname + ".cpp"
@@ -335,19 +387,26 @@ def process (args):
335387
ref = f.split("/")[-1]
336388
filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
337389
elif "." in f:
338-
parts = f.split('.')
339-
cnt = 0
340-
path = ""
341-
for p in parts:
390+
path = f
391+
ref = f.split(".")[-1]
392+
name = f.split(".")[-1]
393+
filename, lineno = find_class_file(path, options["srcdir"])
394+
395+
if not filename:
396+
parts = f.split('.')
397+
cnt = 0
398+
path = ""
399+
for p in parts:
342400
if cnt < len(parts)-1:
343401
path = path + "/+"
344402
else:
345403
path = path + "/"
346404
path = path + p
347405
cnt = cnt + 1
348-
name = f;
349-
ref = parts[-1]
350-
filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
406+
name = f;
407+
ref = parts[-1]
408+
filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
409+
351410
elif "/" in f:
352411
path = f
353412
name = f
@@ -360,7 +419,7 @@ def process (args):
360419
filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"], options['allowscan'])
361420

362421
if not filename:
363-
sys.stderr.write("Warning: Cant find source file for {}\n".format(path))
422+
sys.stderr.write("Warning: Cant find source file for {}\n".format(f))
364423
else:
365424
h = read_help (filename, lineno)
366425

‎doc/mkqhcp.py‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
#!/usr/bin/python3
22

33
## mkqhcp.py
4-
## Version 1.0.3
4+
## Version 1.0.5
55

66
## Copyright 2022-2023 John Donoghue
77
##
@@ -51,14 +51,23 @@ def process(name):
5151
title = e.group("title")
5252
break
5353

54+
# section
5455
h2_match = re.compile(r'.*<h2 class="chapter"[^>]*>(?P<title>[^<]+)</h2>.*')
56+
# appendix
57+
h2a_match = re.compile(r'.*<h2 class="appendix"[^>]*>(?P<title>[^<]+)</h2>.*')
58+
# index
59+
h2i_match = re.compile(r'.*<h2 class="unnumbered"[^>]*>(?P<title>[^<]+)</h2>.*')
60+
5561
h3_match = re.compile(r'.*<h3 class="section"[^>]*>(?P<title>[^<]+)</h3>.*')
5662
h4_match = re.compile(r'.*<h4 class="subsection"[^>]*>(?P<title>[^<]+)</h4>.*')
5763
tag_match1 = re.compile(r'.*<span id="(?P<tag>[^"]+)"[^>]*></span>.*')
5864
#tag_match2 = re.compile(r'.*<div class="[sub]*section" id="(?P<tag>[^"]+)"[^>]*>.*')
5965
tag_match2 = re.compile(r'.*<div class="[sub]*section[^"]*" id="(?P<tag>[^"]+)"[^>]*>.*')
6066
tag_match3 = re.compile(r'.*<div class="chapter-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
67+
tag_match4 = re.compile(r'.*<div class="appendix-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
68+
tag_match5 = re.compile(r'.*<div class="unnumbered-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
6169
index_match = re.compile(r'.*<h4 class="subsection"[^>]*>[\d\.\s]*(?P<name>[^<]+)</h4>.*')
70+
index_match2 = re.compile(r'.*<h4 class="subsection"[^>]*><span>[\d\.\s]*(?P<name>[^<]+)<.*')
6271

6372
tag = "top"
6473
has_h2 = False
@@ -82,10 +91,18 @@ def process(name):
8291
e = tag_match2.match(line)
8392
if not e:
8493
e = tag_match3.match(line)
94+
if not e:
95+
e = tag_match4.match(line)
96+
if not e:
97+
e = tag_match5.match(line)
8598
if e:
8699
tag = e.group("tag")
87100

88101
e = h2_match.match(line)
102+
if not e:
103+
e = h2a_match.match(line)
104+
if not e:
105+
e = h2i_match.match(line)
89106
if e:
90107
if has_h3:
91108
f.write(' </section>\n')
@@ -123,10 +140,14 @@ def process(name):
123140
e = tag_match1.match(line)
124141
if not e:
125142
e = tag_match2.match(line)
143+
126144
if e:
127145
tag = e.group("tag")
128146

147+
129148
e = index_match.match(line)
149+
if not e:
150+
e = index_match2.match(line)
130151
if e:
131152
f.write(' <keyword name="{}" ref="{}.html#{}"></keyword>\n'.format(e.group("name"), name, tag))
132153

0 commit comments

Comments
 (0)