diff --git a/.gitignore b/.gitignore index ed08d45..30c9680 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ tuned-*.tar.bz2 *~ *.html doc/manual/modules/performance/ref_available-tuned-plug-ins.adoc +doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc diff --git a/compile_plugin_docs.py b/compile_plugin_docs.py deleted file mode 100644 index cb9883d..0000000 --- a/compile_plugin_docs.py +++ /dev/null @@ -1,36 +0,0 @@ - -import argparse -import os -import inspect -from tuned.utils.class_loader import ClassLoader -from tuned.plugins.base import Plugin - - -class PluginDocLoader(ClassLoader): - def __init__(self): - super(PluginDocLoader, 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(PluginDocLoader().load_all_classes(), 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("== **%s**\n" % plugin_name) - out_file.write(inspect.cleandoc(plugin.__doc__)) - out_file.write("\n") diff --git a/doc/manual/Makefile b/doc/manual/Makefile index 1173a4f..37f05bc 100644 --- a/doc/manual/Makefile +++ b/doc/manual/Makefile @@ -1,7 +1,8 @@ .PHONY: clean -index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc ../../tuned/plugins/plugin_*.py - $(PYTHON) ../../compile_plugin_docs.py modules/performance/ref_available-tuned-plug-ins_intro.adoc modules/performance/ref_available-tuned-plug-ins.adoc +index.html: master.adoc assemblies/*.adoc meta/*.adoc modules/performance/*.adoc ../../tuned/plugins/plugin_*.py ../../tuned/profiles/functions/function_*.py + $(PYTHON) ./compile_plugin_docs.py ../../tuned/plugins plugin_ Plugin modules/performance/ref_available-tuned-plug-ins_intro.adoc modules/performance/ref_available-tuned-plug-ins.adoc + $(PYTHON) ./compile_plugin_docs.py ../../tuned/profiles/functions function_ Function modules/performance/ref_built-in-functions-available-in-tuned-profiles_intro.adoc modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc asciidoctor -o index.html master.adoc || asciidoc -d book -o index.html master.adoc install: index.html @@ -9,4 +10,5 @@ install: index.html clean: rm -f modules/performance/ref_available-tuned-plug-ins.adoc + rm -f modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc rm -f *.html diff --git a/doc/manual/compile_plugin_docs.py b/doc/manual/compile_plugin_docs.py new file mode 100755 index 0000000..34398ad --- /dev/null +++ b/doc/manual/compile_plugin_docs.py @@ -0,0 +1,53 @@ +#!/usr/bin/env python3 +import argparse +import ast +import os +import inspect + + +class DocLoader: + def __init__(self, directory, prefix, base): + self._directory = directory + self._prefix = prefix + self._base = base + + def _load_doc(self, module_path): + with open(module_path, "r") as file: + tree = ast.parse(file.read(), filename=module_path) + for node in ast.walk(tree): + if isinstance(node, ast.ClassDef) and any( + hasattr(base, "attr") and base.attr == self._base for base in node.bases + ): + return inspect.cleandoc(ast.get_docstring(node)) + return "" + + def load_all_docs(self): + docs = {} + for filename in os.listdir(self._directory): + if not filename.startswith(self._prefix): + continue + name = filename.split(".")[0].split("_", 1)[1] + path = os.path.join(self._directory, filename) + docs[name] = self._load_doc(path) + return docs + + +if __name__ == "__main__": + parser = argparse.ArgumentParser() + parser.add_argument("directory") + parser.add_argument("prefix") + parser.add_argument("base") + parser.add_argument("intro") + parser.add_argument("out") + args = parser.parse_args() + + with open(args.intro, "r") as intro_file: + intro = intro_file.read() + + doc_loader = DocLoader(args.directory, args.prefix, args.base) + class_docs = doc_loader.load_all_docs() + + with open(args.out, "w") as out_file: + out_file.write(intro) + for name, docs in class_docs.items(): + out_file.writelines(["\n", "== **%s**\n" % name, "%s\n" % docs]) diff --git a/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc b/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc deleted file mode 100644 index dafdc20..0000000 --- a/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles.adoc +++ /dev/null @@ -1,60 +0,0 @@ -:_module-type: REFERENCE -[id="built-in-functions-available-in-tuned-profiles_{context}"] -= Built-in functions available in TuneD profiles - -[role="_abstract"] -The following built-in functions are available in all *TuneD* profiles: - -`PROFILE_DIR`:: -Returns the directory path where the profile and the `tuned.conf` file are located. - -`exec`:: -Executes a process and returns its output. - -`assertion`:: -Compares two arguments. If they _do not match_, the function logs text from the first argument and aborts profile loading. - -`assertion_non_equal`:: -Compares two arguments. If they _match_, the function logs text from the first argument and aborts profile loading. - -`kb2s`:: -Converts kilobytes to disk sectors. - -`s2kb`:: -Converts disk sectors to kilobytes. - -`strip`:: -Creates a string from all passed arguments and deletes both leading and trailing white space. - -`virt_check`:: -Checks whether *TuneD* is running inside a virtual machine (VM) or on bare metal: -+ -* Inside a VM, the function returns the first argument. -* On bare metal, the function returns the second argument, even in case of an error. - -`cpulist_invert`:: -Inverts a list of CPUs to make its complement. For example, on a system with 4 CPUs, numbered from 0 to 3, the inversion of the list `0,2,3` is `1`. - -`cpulist2hex`:: -Converts a CPU list to a hexadecimal CPU mask. - -`cpulist2hex_invert`:: -Converts a CPU list to a hexadecimal CPU mask and inverts it. - -`hex2cpulist`:: -Converts a hexadecimal CPU mask to a CPU list. - -`cpulist_online`:: -Checks whether the CPUs from the list are online. Returns the list containing only online CPUs. - -`cpulist_present`:: -Checks whether the CPUs from the list are present. Returns the list containing only present CPUs. - -`cpulist_unpack`:: -Unpacks a CPU list in the form of `1-3,4` to `1,2,3,4`. - -`cpulist_pack`:: -Packs a CPU list in the form of `1,2,3,5` to `1-3,5`. - -`intel_recommended_pstate`:: -Returns recommended intel_pstate CPUFreq driver mode based on processor generation. diff --git a/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles_intro.adoc b/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles_intro.adoc new file mode 100644 index 0000000..2b36414 --- /dev/null +++ b/doc/manual/modules/performance/ref_built-in-functions-available-in-tuned-profiles_intro.adoc @@ -0,0 +1,6 @@ +:_module-type: REFERENCE +[id="built-in-functions-available-in-tuned-profiles_{context}"] += Built-in functions available in TuneD profiles + +[role="_abstract"] +The following built-in functions are available in all *TuneD* profiles: