docs: add links also for missing components

Author: hansu

docs/src/Submakefile

@@ -336,6 +336,7 @@ DOTFILES=$(shell find . -name "*.dot") $(shell find ../docs/src/ -name "*.dot")
 .PHONY: svgs_made_from_dots
 svgs_made_from_dots: $(DOTFILES:.dot=.svg)
 
+docs: gen_complist
 ifeq ($(BUILD_DOCS_PDF),yes)
 docs: pdfdocs
 install-doc: install-doc-pdf
@@ -353,17 +354,17 @@ htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en
 .htmldoc-stamp: copy_asciidoc_files gen_complist $(HTML_TARGETS) .images-stamp .include-stamp
 	touch $@
 
-.PHONY: copy_asciidoc_files
+.PHONY: copy_asciidoc_files gen_complist gen_complist_links
 copy_asciidoc_files:
 	cp -f /etc/asciidoc/stylesheets/*.css $(DOC_DIR)/html
 	cp -f /etc/asciidoc/javascripts/*.js $(DOC_DIR)/html
 
 gen_complist:
-	python3 $(DOC_SRCDIR)/gen_complist.py
+	python3 $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc
 	touch $(DOC_SRCDIR)/hal/components.adoc
 
-.PHONY gen_complist_links:
-	python3 $(DOC_SRCDIR)/gen_complist.py links
+gen_complist_links:
+	python3 $(DOC_SRCDIR)/gen_complist.py $(DOC_SRCDIR)/hal/components.adoc links
 
 checkref: checkref_en checkref_de checkref_es checkref_fr checkref_hu checkref_nb checkref_vi checkref_zh_CN
 

docs/src/gen_complist.py

@@ -5,28 +5,27 @@
 # generate_links()
 #       Generates a copy of components.adoc with added links to the man pages for the components.
 
-from os import listdir
-from os.path import isfile, join
+import os
 import re
 import sys
 
-man1_path = '../docs/html/man/man1'
-man1_files = {f.replace('.1.html', '') for f in listdir(man1_path) if isfile(join(man1_path, f))}
-man9_path = '../docs/html/man/man9'
-man9_files = {f.replace('.9.html', '') for f in listdir(man9_path) if isfile(join(man9_path, f))}
-man = [man1_files,man9_files]
+man1_path = '../docs/man/man1'
+man1_files = {f.replace('.1', '') for f in os.listdir(man1_path) if os.path.isfile(os.path.join(man1_path, f))}
+man9_path = '../docs/man/man9'
+man9_files = {f.replace('.9', '') for f in os.listdir(man9_path) if os.path.isfile(os.path.join(man9_path, f))}
+man = {'1':man1_files, '9':man9_files}
 doc1 = set()
 doc9 = set()
-components = [doc1,doc9]
+components = {'1':doc1, '9':doc9}
 section_switch = '[[sec:realtime-components]]'
-complist_path = '../docs/src/hal/components.adoc'
+# complist_path = '../docs/src/hal/components.adoc'
 
-def generate_complist():
+def generate_complist(complist_path):
     file1 = open(complist_path, 'r')
-    comp_index = 0
+    manpage = '1'
     for line in file1:
         if section_switch in line:
-            comp_index = 1
+            manpage = '9'
 
         if line[0] == '|' and line[1] != '=':
             splitted = line.split('|')
@@ -35,15 +34,15 @@ def generate_complist():
                     comp = re.search('\[.*\]', splitted[1]).group()
                 else:
                     comp = splitted[1]
-                components[comp_index].add(comp.strip('[] '))
+                components[manpage].add(comp.strip('[] '))
 
     file1.close()
     miss1 = man1_files.difference(doc1)
     obs1 = doc1.difference(man1_files)
     miss9 = man9_files.difference(doc9)
     obs9 = doc9.difference(man9_files)
-
-    file2 = open('../docs/src/hal/components_gen1.adoc', 'w')
+    gen1_filename = '../docs/src/hal/components_gen1.adoc'
+    file2 = open(gen1_filename, 'w')
     if len(miss1) > 0:
         file2.write('=== Not categorized (auto generated)\n')
         file2.write('[{tab_options}]\n|=======================\n')
@@ -57,8 +56,8 @@ def generate_complist():
             file2.write('| ' + i + ' |||\n')
         file2.write('|=======================\n')
     file2.close()
-
-    file3 = open('../docs/src/hal/components_gen9.adoc', 'w')
+    gen9_filename = '../docs/src/hal/components_gen9.adoc'
+    file3 = open(gen9_filename, 'w')
     if len(miss9) > 0:
         file3.write('=== Not categorized (auto generated)\n')
         file3.write('[{tab_options}]\n|=======================\n')
@@ -73,42 +72,53 @@ def generate_complist():
         file3.write('|=======================\n')
     file3.close()
 
+    generate_links(gen1_filename, '1', False)
+    generate_links(gen9_filename, '9', False)
+
     print('gen_complist: Added {} uncategorized and {} obsolete entries to hal component list (man1)'.format(len(miss1), len(obs1)))
     print('gen_complist: Added {} uncategorized and {} obsolete entries to hal component list (man9)'.format(len(miss9), len(obs9)))
 
 
-def generate_links():
-    file1 = open(complist_path, 'r')
-    file1_links = open('../docs/src/hal/components_links.adoc', 'w')
-    comp_index = 0
-    manpage = '1'
-    for line in file1:
+def generate_links(filename, manpage='1', create_backup=True):
+    file = open(filename, 'r')
+    file_links = []
+    links_added = 0
+    for line in file:
         if section_switch in line:
-            comp_index = 1
             manpage = '9'
 
         if line[0] == '|' and line[1] != '=':
             splitted = line.split('|')
 
             if 'link:' in splitted[1]:
                 link = re.search('(?<=link:).*(?=\[)', splitted[1]).group()
-                if not isfile(join('../docs/html/hal',link)):
-                    print('broken link:', link)
+                if not os.path.isfile(os.path.join('../docs/html/hal',link)):
+                    print('gen_complist_link: Broken link:', link)
             else:
                 comp = splitted[1].strip(' ')
-                if comp in man[comp_index]:
+                if comp in man[manpage]:
                     line = line.replace(comp, 'link:../man/man'+manpage+'/'+comp+'.'+manpage+'.html['+comp+']', 1)
+                    links_added += 1
 
-        file1_links.write(line)
+        file_links.append(line)
+
+    file.close()
+
+    if links_added:
+        if create_backup:
+            os.rename(filename, filename+'~')        
+        file = open(filename, 'w')
+        for line in file_links:
+            file.write(line)
+        file.close()
+        print('gen_complist_links: Added {} link(s) to {}'.format(links_added, filename))
 
-    file1.close()
-    file1_links.close()
 
 if __name__ == "__main__":
 
     if len(sys.argv) > 1:
-        if sys.argv[1] == 'links':
-            generate_links()
-
-    else:
-        generate_complist()
+        if len(sys.argv) > 2:
+            if sys.argv[2] == 'links':
+                generate_links(sys.argv[1])
+        else:
+            generate_complist(sys.argv[1])