update doc generation

* Makefile: update to handle anchor link

* doc/arduino.css: minor updates to styles

* doc/mkfuncdocs.py, doc/mkqhcp.py: latest doc gen

Author: lostbard

Makefile

@@ -18,6 +18,7 @@ GREP      ?= grep
 TAR       ?= tar
 TEXI2PDF  ?= texi2pdf -q
 MAKEINFO  ?= makeinfo
+MAKEINFO_HTML_OPTIONS := --no-headers --set-customization-variable 'COPIABLE_LINKS 0' --set-customization-variable 'COPIABLE_ANCHORS 0' --no-split 
 CUT ?= cut
 TR ?= tr
 
@@ -159,7 +160,7 @@ doc/$(PACKAGE).pdf: doc/$(PACKAGE).texi doc/functions.texi doc/version.texi
 	cd doc && $(RM) -f arduino.aux  arduino.cp  arduino.cps  arduino.fn  arduino.fns  arduino.log  arduino.toc
 
 doc/$(PACKAGE).html: doc/$(PACKAGE).texi doc/functions.texi doc/version.texi
-	cd doc && SOURCE_DATE_EPOCH=$(REPO_TIMESTAMP) $(MAKEINFO) --html --css-ref=$(PACKAGE).css  --no-split --output=${PACKAGE}.html $(PACKAGE).texi
+	cd doc && SOURCE_DATE_EPOCH=$(REPO_TIMESTAMP) $(MAKEINFO) --html --css-ref=$(PACKAGE).css $(MAKEINFO_HTML_OPTIONS) --output=${PACKAGE}.html $(PACKAGE).texi
 
 doc/$(PACKAGE).qhc: doc/$(PACKAGE).html
 	# try also create qch file if can

doc/arduino.css

@@ -8,12 +8,16 @@ pre.example {
   background-color: #fdf6e3;
   padding: 0.5em; }
 
-table.cartouche {
+a { color: #268bd2; /* blue */ }
+
+a:visited { color: #d33682; /* magenta */ }
+
+table.cartouche1 {
   border: 1px solid #948473;
   background-color: #FFE3C6;
   width: 100%;
 }
-table.cartouche td, table.cartouche th {
+table.cartouche1 td, table.cartouche1 th {
   border: 1px solid #948473;
   padding: 4px 4px;
 }

doc/mkfuncdocs.py

@@ -1,6 +1,6 @@
 #!/usr/bin/python3
 
-## Copyright 2018-2023 John Donoghue
+## Copyright 2018-2024 John Donoghue
 ##
 ## This program is free software: you can redistribute it and/or modify it
 ## under the terms of the GNU General Public License as published by
@@ -16,7 +16,7 @@
 ## along with this program.  If not, see
 ## <https://www.gnu.org/licenses/>.
 
-## mkfuncdocs v1.0.7
+## mkfuncdocs v1.0.8
 ## mkfuncdocs.py will attempt to extract the help texts from functions in src
 ## dirs, extracting only those that are in the specifed INDEX file and output them
 ## to stdout in texi format
@@ -89,6 +89,36 @@ def find_defun_line_in_file(filename, fnname):
 
   return -1
 
+def find_function_line_in_file(filename, fnname):
+  linecnt = 0
+  func = False
+  defun_line=re.compile(r"^\s*function \s*")
+  with open(filename, 'rt') as f:
+    for line in f:
+      if func == True:
+          x = line.strip()
+          if x.startswith("## -*- texinfo -*-"):
+            return linecnt
+          else:
+            func = False
+
+      if re.match(defun_line, line):
+        if line.find("=") != -1:
+           x = line.split("=")
+           x = x[-1]
+        else:
+           x = line.replace("function ", "")
+
+        x = x.split("(")
+        x = x[0].strip()
+        if x == fnname:
+          func = True
+
+      linecnt = linecnt + 1
+
+  return -1
+
+
 def read_m_file(filename, skip=0):
   help = []
   inhelp = False
@@ -195,6 +225,29 @@ def read_index (filename, ignore):
 
   return index;
 
+def find_class_file(fname, paths):
+  
+  for f in paths:
+      # class constructor ?
+      name = f + "/@" + fname + "/" + fname + ".m"
+      if os.path.isfile(name):
+        return name, 0
+
+      # perhaps classname.func format ?
+      x = fname.split(".")
+      if len(x) > 0:
+          zname = x.pop()
+          cname = ".".join(x)
+          name = f + "/" + cname + ".m"
+          if os.path.isfile(name):
+            idx = find_function_line_in_file(name, zname)
+            if idx >= 0:
+              return name, idx
+          name = f + "/@" + cname + "/" + zname + ".m"
+          if os.path.isfile(name):
+            return name, 0
+  return None, -1
+
 def find_func_file(fname, paths, prefix, scanfiles=False):
   for f in paths:
       name = f + "/" + fname + ".m"
@@ -205,7 +258,6 @@ def find_func_file(fname, paths, prefix, scanfiles=False):
       if os.path.isfile(name):
         return name, 0
       name = f + "/" + fname + ".cc"
-      name = f + "/" + fname + ".cc"
       if os.path.isfile(name):
         return name, 0
       name = f + "/" + fname + ".cpp"
@@ -335,19 +387,26 @@ def process (args):
         ref = f.split("/")[-1]
         filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
       elif "." in f:
-        parts = f.split('.')
-        cnt  = 0
-        path = ""
-        for p in parts:
+        path = f
+        ref = f.split(".")[-1]
+        name = f.split(".")[-1]
+        filename, lineno = find_class_file(path, options["srcdir"])
+
+        if not filename:
+          parts = f.split('.')
+          cnt  = 0
+          path = ""
+          for p in parts:
             if cnt < len(parts)-1:
               path = path + "/+"
             else:
               path = path + "/"
             path = path + p
             cnt = cnt + 1
-        name = f;
-        ref = parts[-1]
-        filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
+          name = f;
+          ref = parts[-1]
+          filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"])
+
       elif "/" in f:
         path = f
         name = f
@@ -360,7 +419,7 @@ def process (args):
         filename, lineno = find_func_file(path, options["srcdir"], options["funcprefix"], options['allowscan'])
 
       if not filename:
-        sys.stderr.write("Warning: Cant find source file for {}\n".format(path))
+        sys.stderr.write("Warning: Cant find source file for {}\n".format(f))
       else:
         h = read_help (filename, lineno)
 

doc/mkqhcp.py

@@ -1,7 +1,7 @@
 #!/usr/bin/python3
 
 ## mkqhcp.py
-## Version 1.0.3
+## Version 1.0.4
 
 ## Copyright 2022-2023 John Donoghue
 ##
@@ -51,13 +51,21 @@ def process(name):
           title = e.group("title")
           break
 
+  # section
   h2_match = re.compile(r'.*<h2 class="chapter"[^>]*>(?P<title>[^<]+)</h2>.*')
+  # appendix
+  h2a_match = re.compile(r'.*<h2 class="appendix"[^>]*>(?P<title>[^<]+)</h2>.*')
+  # index
+  h2i_match = re.compile(r'.*<h2 class="unnumbered"[^>]*>(?P<title>[^<]+)</h2>.*')
+
   h3_match = re.compile(r'.*<h3 class="section"[^>]*>(?P<title>[^<]+)</h3>.*')
   h4_match = re.compile(r'.*<h4 class="subsection"[^>]*>(?P<title>[^<]+)</h4>.*')
   tag_match1 = re.compile(r'.*<span id="(?P<tag>[^"]+)"[^>]*></span>.*')
   #tag_match2 = re.compile(r'.*<div class="[sub]*section" id="(?P<tag>[^"]+)"[^>]*>.*')
   tag_match2 = re.compile(r'.*<div class="[sub]*section[^"]*" id="(?P<tag>[^"]+)"[^>]*>.*')
   tag_match3 = re.compile(r'.*<div class="chapter-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
+  tag_match4 = re.compile(r'.*<div class="appendix-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
+  tag_match5 = re.compile(r'.*<div class="unnumbered-level-extent" id="(?P<tag>[^"]+)"[^>]*>.*')
   index_match = re.compile(r'.*<h4 class="subsection"[^>]*>[\d\.\s]*(?P<name>[^<]+)</h4>.*')
 
   tag = "top"
@@ -82,10 +90,18 @@ def process(name):
               e = tag_match2.match(line)
           if not e:
               e = tag_match3.match(line)
+          if not e:
+              e = tag_match4.match(line)
+          if not e:
+              e = tag_match5.match(line)
           if e:
               tag = e.group("tag")
 
           e = h2_match.match(line)
+          if not e:
+              e = h2a_match.match(line)
+          if not e:
+              e = h2i_match.match(line)
           if e:
               if has_h3:
                   f.write('          </section>\n')