docs: generate list of missing components

Author: hansu

.gitignore

@@ -13,6 +13,8 @@ build-stamp
 .tmp*
 # Ignore generated html files, 
 /docs/src/*/*.html
+docs/src/hal/components_gen1.adoc
+docs/src/hal/components_gen9.adoc
 # docs/html/.gitignore is for the html directory
 debian/*.debhelper.log
 rtlib/Module.symvers

docs/src/Submakefile

@@ -350,14 +350,17 @@ pdfdocs: svgs_made_from_dots $(PDF_TARGETS)
 
 htmldocs: svgs_made_from_dots .htmldoc-stamp checkref_en
 
-.htmldoc-stamp: copy_asciidoc_files $(HTML_TARGETS) .images-stamp .include-stamp
+.htmldoc-stamp: copy_asciidoc_files gen_complist $(HTML_TARGETS) .images-stamp .include-stamp
 	touch $@
 
 .PHONY: copy_asciidoc_files
 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
+
 checkref: checkref_en checkref_de checkref_es checkref_fr checkref_hu checkref_nb checkref_vi checkref_zh_CN
 
 checkref_en: $(DOC_TARGETS_HTML_EN) $(DOC_DIR)/html/index.html $(DOC_DIR)/html/gcode.html .htmldoc-stamp

docs/src/asciideps

@@ -9,6 +9,12 @@ includes () {
 	DIR=`dirname "$1"`
 
 	for f in `sed -ne "s|^include::\(.*\)\[\]$|$DIR/\1|p" "$1"`; do
+		# components_gen.adoc will contain only generated content
+		case "$f" in
+			*/components_gen*.adoc)
+			touch "$f"
+			;;
+		esac
 		echo "$f"
 		includes "$f"
 	done

docs/src/gen_complist.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+# This file compares the entries in the component list (components.adoc) with the 
+# available man pages and adds a tables for missing components.
+
+from os import listdir
+from os.path import isfile, join
+
+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))}
+
+file1 = open('../docs/src/hal/components.adoc', 'r')
+section_switch = '[[sec:realtime-components]]'
+doc1 = set()
+doc9 = set()
+components = [doc1,doc9]
+comp_index = 0
+for line in file1:
+    if section_switch in line:
+        comp_index = 1
+    
+    if line[0] == '|' and line[1] != '=':
+        line = line.split('|')
+        if line[1].strip() != '':
+            components[comp_index].add(line[1].strip())
+            #print(line[1].strip(), "-->", comp_index)
+
+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')
+if len(miss1) > 0:
+    file2.write('=== Not categorized (auto generated)\n')
+    file2.write('[{tab_options}]\n|=======================\n')
+    for i in sorted(miss1):
+        file2.write('| ' + i + ' |||\n')
+    file2.write('|=======================\n')
+if len(obs1) > 0:
+    file2.write('\n=== Obsolete (auto generated)\n')
+    file2.write('[{tab_options}]\n|=======================\n')
+    for i in sorted(obs1):
+        file2.write('| ' + i + ' |||\n')
+    file2.write('|=======================\n')
+file2.close()
+
+file3 = open('../docs/src/hal/components_gen9.adoc', 'w')
+if len(miss9) > 0:
+    file3.write('=== Not categorized (auto generated)\n')
+    file3.write('[{tab_options}]\n|=======================\n')
+    for i in sorted(miss9):
+        file3.write('| ' + i + ' |||\n')
+    file3.write('|=======================\n')
+if len(obs9) > 0:
+    file3.write('\n=== Obsolete (auto generated)\n')
+    file3.write('[{tab_options}]\n|=======================\n')
+    for i in sorted(obs9):
+        file3.write('| ' + i + ' |||\n')
+    file3.write('|=======================\n')
+file3.close()
+
+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)))

docs/src/hal/components.adoc

@@ -34,24 +34,22 @@ man axis (or perhaps 'man 1 axis' if your system requires it.)
 
 [{tab_options}]
 |=======================
-| gs2 | HAL userspace component for Automation Direct GS2 VFD's. ||
-| mb2hal | ||
+| mb2hal | MB2HAL is a generic userspace HAL component to communicate with one or more Modbus devices. Modbus RTU and Modbus TCP is supported.||
 |=======================
 
 === Diagnostic and Configuration Tools
 
 [{tab_options}]
 |=======================
 | halmeter | Observe HAL pins, signals, and parameters. ||
-| halshow |||
-| halscope |||
+| halshow  | Show HAL parameters, pins and signals ||
+| halscope | Software oscilloscope for viewing real time waveforms of HAL pins and signals ||
 |=======================
 
 === Other
 
 [{tab_options}]
 |=======================
-| comp | Build, compile and install LinuxCNC HAL components. ||
 | halcmd | Manipulate the Enhanced Machine Controller HAL from the command line. ||
 | hal_input | Control HAL pins with any Linux input device, including USB HID devices. ||
 | halrun | Manipulate the Enhanced Machine Controller HAL from the command line. ||
@@ -63,6 +61,8 @@ man axis (or perhaps 'man 1 axis' if your system requires it.)
 | shuttle | control HAL pins with the ShuttleXpress and ShuttlePRO devices made by Contour Design. ||
 |=======================
 
+include::components_gen1.adoc[]
+
 [[sec:realtime-components]]
 
 == Realtime Components
@@ -160,6 +160,7 @@ Limit its slew rate to less than maxv per second. Limit its second derivative to
 
 [{tab_options}]
 |=======================
+| gs2 | HAL userspace component for Automation Direct GS2 VFD's. ||
 | hal_ppmc | Pico Systems <<cha:pico-drivers,driver>> for analog servo, PWM and Stepper controller. ||
 | hm2_7i43 | Mesa Electronics driver for the 7i43 EPP Anything IO board with HostMot2. (See the man page for more information) ||
 | hm2_pci | Mesa Electronics driver for the 5i20, 5i22, 5i23, 4i65, and 4i68 Anything I/O boards, with HostMot2 firmware. (See the man page for more information) ||
@@ -214,6 +215,7 @@ clarkeinv:: (((clarkeinv))) Inverse Clarke transform.
 
 [{tab_options}]
 |=======================
+| comp | Build, compile and install LinuxCNC HAL components. ||
 |motion | Accepts NML motion commands, interacts with HAL in realtime. ||
 |classicladder | Realtime software PLC based on ladder logic. See <<cha:classicladder,ClassicLadder>> chapter for more information. ||
 |threads | Creates hard realtime HAL threads. ||
@@ -255,6 +257,8 @@ to the smoothing level desired. Divide the axis.N.jog-scale values by scale. ||
 | watchdog | Monitor one to thirty-two inputs for a 'heartbeat'. ||
 |=======================
 
+include::components_gen9.adoc[]
+
 == HAL API calls
 
 ----