Merge pull request redhat-performance#693 from zacikpa/autodocs

Automatic generation of plugin docs from their docstrings

.gitignore

@@ -3,3 +3,4 @@
 tuned-*.tar.bz2
 *~
 *.html
+doc/manual/modules/performance/ref_available-tuned-plug-ins.adoc

Makefile

@@ -70,7 +70,7 @@ release-cp: release-dir
 		tuned-adm.bash dbus.conf recommend.conf tuned-main.conf 00_tuned \
 		92-tuned.install bootcmdline modules.conf com.redhat.tuned.policy \
 		tuned-gui.py tuned-gui.glade tuned-ppd.py \
-		tuned-gui.desktop functions $(VERSIONED_NAME)
+		tuned-gui.desktop functions compile_plugin_docs.py $(VERSIONED_NAME)
 	cp -a doc experiments libexec man profiles systemtap tuned contrib icons \
 		tests $(VERSIONED_NAME)
 

compile_plugin_docs.py

@@ -0,0 +1,36 @@
+
+import argparse
+import os
+import inspect
+from tuned.utils.plugin_loader import PluginLoader
+from tuned.plugins.base import Plugin
+
+
+class DocLoader(PluginLoader):
+	def __init__(self):
+		super(DocLoader, self).__init__()
+
+	def _set_loader_parameters(self):
+		self._namespace = "tuned.plugins"
+		self._prefix = "plugin_"
+		self._interface = Plugin
+
+parser = argparse.ArgumentParser()
+parser.add_argument("intro")
+parser.add_argument("out")
+args = parser.parse_args()
+
+with open(args.intro, "r") as intro_file:
+	intro = intro_file.read()
+
+all_plugins = sorted(DocLoader().load_all_plugins(), key=lambda x: x.__module__)
+
+with open(args.out, "w") as out_file:
+	out_file.write(intro)
+	for plugin in all_plugins:
+		plugin_file = inspect.getfile(plugin)
+		plugin_name = os.path.basename(plugin_file)[7:-3]
+		out_file.write("\n")
+		out_file.write(f"== **{plugin_name}**\n")
+		out_file.write(inspect.cleandoc(plugin.__doc__))
+		out_file.write("\n")

doc/manual/Makefile

@@ -1,10 +1,12 @@
 .PHONY: clean
 
-index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc
+index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc ../../tuned/plugins/plugin_*.py
+	python3 ../../compile_plugin_docs.py modules/performance/ref_available-tuned-plug-ins_intro.adoc modules/performance/ref_available-tuned-plug-ins.adoc
 	asciidoctor -o index.html master.adoc || asciidoc -o index.html master.adoc
 
 install: index.html
 	install -Dpm 0644 index.html $(DESTDIR)$(DOCDIR)/manual/index.html
 
 clean:
+	rm -f modules/performance/ref_available-tuned-plug-ins.adoc
 	rm -f *.html

doc/manual/master.adoc

@@ -1,5 +1,5 @@
-:revnumber: 2.10.0
-:revdate: 2019-01-04
+:revnumber: 2.24.1
+:revdate: 2024-10-09
 :keywords: documentation, tuned, performance, power, linux
 :toc:
 

doc/manual/modules/performance/ref_available-tuned-plug-ins_intro.adoc

@@ -0,0 +1,6 @@
+:_module-type: REFERENCE
+[id="available-tuned-plug-ins_{context}"]
+= Available TuneD plug-ins
+
+[role="_abstract"]
+This section lists all monitoring and tuning plug-ins currently available in *TuneD*.

tuned/plugins/plugin_acpi.py

@@ -10,18 +10,15 @@
 
 class ACPIPlugin(base.Plugin):
 	"""
-	`acpi`::
-
 	Configures the ACPI driver.
-	+
+
 	The only currently supported option is
 	[option]`platform_profile`, which sets the ACPI
 	platform profile sysfs attribute,
 	a generic power/performance preference API for other drivers.
 	Multiple profiles can be specified, separated by `|`.
 	The first available profile is selected.
-	+
-	--
+
 	.Selecting a platform profile
 	====
 	----
@@ -31,7 +28,6 @@ class ACPIPlugin(base.Plugin):
 	Using this option, *TuneD* will try to set the platform profile
 	to `balanced`. If that fails, it will try to set it to `low-power`.
 	====
-	--
 	"""
 	def __init__(self, *args, **kwargs):
 		super(ACPIPlugin, self).__init__(*args, **kwargs)

tuned/plugins/plugin_audio.py

@@ -13,20 +13,18 @@
 
 class AudioPlugin(hotplug.Plugin):
 	"""
-	`audio`::
-	
 	Sets audio cards power saving options. The plug-in sets the auto suspend
 	timeout for audio codecs to the value specified by the [option]`timeout`
 	option.
-	+
+
 	Currently, the `snd_hda_intel` and `snd_ac97_codec` codecs are
 	supported and the [option]`timeout` value is in seconds. To disable
 	auto suspend for these codecs, set the [option]`timeout` value
 	to `0`. To enforce the controller reset, set the option
 	[option]`reset_controller` to `true`. Note that power management
 	is supported per module. Hence, the kernel module names are used as
 	device names.
-	+
+
 	.Set the timeout value to 10s and enforce the controller reset
 	====
 	----