lisa: Include some private functions in documentation

Use :meta public: info field to include some private functions in the
documentation.

https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html

Command used:
    perl -0pi -e 's/(def _[^_].*:\n *"""\n( *))/\1:meta public:\n\n\2/g' lisa/**.py

doc/energy_analysis.rst

@@ -208,11 +208,9 @@ Energy model
 
 .. automodule:: lisa.energy_model
    :members:
-   :private-members: _CpuTree
 
 Energy meters
 +++++++++++++
 
 .. automodule:: lisa.energy_meter
    :members:
-   :private-members: _DevlibContinuousEnergyMeter

doc/kernel_tests.rst

@@ -194,7 +194,6 @@ Base classes
 
 .. automodule:: lisa.tests.base
    :members:
-   :private-members: _from_target
 
 .. TODO:: Make those imports more generic
 
@@ -224,7 +223,6 @@ Load tracking tests
 
 .. automodule:: lisa.tests.scheduler.load_tracking
    :members:
-   :private-members: _from_target
 
 |
 

lisa/energy_meter.py

@@ -246,7 +246,11 @@ def report(self, out_dir, out_file='energy.json'):
 
 
 class _DevlibContinuousEnergyMeter(EnergyMeter):
-    """Common functionality for devlib Instruments in CONTINUOUS mode"""
+    """
+    :meta public:
+
+    Common functionality for devlib Instruments in CONTINUOUS mode
+    """
 
     def reset(self):
         self._instrument.start()

lisa/energy_model.py

@@ -82,7 +82,10 @@ def __new__(cls, capacity=None, power=None):
 
 
 class _CpuTree(Loggable):
-    """Internal class. Abstract representation of a CPU topology.
+    """
+    :meta public:
+
+    Internal class. Abstract representation of a CPU topology.
 
     Each node contains either a single CPU or a set of child nodes.
 

lisa/test_example.py

@@ -61,6 +61,8 @@ def __init__(self, res_dir, plat_info, shell_output):
     @classmethod
     def _from_target(cls, target: Target, *, res_dir: ArtifactPath, ftrace_coll: FtraceCollector = None) -> 'ExampleTestBundle':
         """
+        :meta public:
+
         This class method is the main way of creating a :class:`ExampleTestBundle`.
 
         It takes a first (positional) ``target`` parameter, which is a live
@@ -133,6 +135,8 @@ def _from_target(cls, target: Target, *, res_dir: ArtifactPath, ftrace_coll: Ftr
     @classmethod
     def _get_rtapp_profile(cls, plat_info):
         """
+        :meta public:
+
         This class method is in charge of generating an rt-app profile, to
         configure the workload that will be run using
         :meth:`lisa.tests.base.RTATestBundle.run_rtapp`.

lisa/tests/base.py

@@ -860,6 +860,8 @@ def get_tags(self):
     @abc.abstractmethod
     def _from_target(cls, target, *, res_dir):
         """
+        :meta public:
+
         Internals of the target factory method.
 
         .. note:: This must be a classmethod, and all parameters except
@@ -943,6 +945,8 @@ def from_target(cls, target: Target, *, res_dir: ArtifactPath = None, **kwargs):
     @classmethod
     def _get_filepath(cls, res_dir):
         """
+        :meta public:
+
         Returns the path of the file containing the serialized object in
         ``res_dir`` folder.
         """
@@ -977,6 +981,8 @@ def update_refs(obj):
     @property
     def _children_test_bundles(self):
         """
+        :meta public:
+
         List of references to :class:`TestBundle` instances ``self`` relies on
         (directly *and* indirectly).
 
@@ -1009,9 +1015,6 @@ def from_dir(cls, res_dir, update_res_dir=True):
 
         It uses :meth:`_get_filepath` to get the name of the serialized file to
         reload.
-
-
-         .. automethod:: _get_filepath
         """
         res_dir = ArtifactPath(root=res_dir, relative='')
 
@@ -1643,6 +1646,8 @@ def add_buffer(task):
     @abc.abstractmethod
     def _get_rtapp_profile(cls, plat_info):
         """
+        :meta public:
+
         :returns: a :class:`dict` with task names as keys and
           :class:`lisa.wlgen.rta.RTATask` as values
 
@@ -1795,13 +1800,17 @@ def run_rtapp(cls, target, res_dir, profile=None, ftrace_coll=None, cg_cfg=None,
     @classmethod
     def _run_rtapp(cls, *args, **kwargs):
         """
+        :meta public:
+
         Has been renamed to :meth:`~lisa.tests.base.RTATestBundle.run_rtapp`, as it really is part of the public API.
         """
         return cls.run_rtapp(*args, **kwargs)
 
     @classmethod
     def _from_target(cls, target: Target, *, res_dir: ArtifactPath, ftrace_coll: FtraceCollector = None) -> 'RTATestBundle':
         """
+        :meta public:
+
         Factory method to create a bundle using a live target
 
         This will execute the rt-app workload described in

lisa/tests/cpufreq/sanity.py

@@ -39,6 +39,8 @@ def __init__(self, res_dir, plat_info, cpu, freq, work):
     @classmethod
     def _from_target(cls, target: Target, *, res_dir: ArtifactPath, cpu, freq, switch_governor=True) -> 'UserspaceSanityItem':
         """
+        :meta public:
+
         Create a :class:`UserspaceSanityItem` from a live :class:`lisa.target.Target`.
 
         :param cpu: CPU to run on.

lisa/tests/scheduler/eas_behaviour.py

@@ -102,6 +102,8 @@ def check_from_target(cls, target):
     @classmethod
     def _from_target(cls, target: Target, *, res_dir: ArtifactPath = None, ftrace_coll: FtraceCollector = None) -> 'EASBehaviour':
         """
+        :meta public:
+
         Factory method to create a bundle using a live target
 
         This will execute the rt-app workload described in

lisa/tests/scheduler/load_tracking.py

@@ -59,6 +59,8 @@ class LoadTrackingHelpers:
     @classmethod
     def _get_blacklisted_cpus(cls, plat_info):
         """
+        :meta public:
+
         Consider some CPUs as blacklisted when the load would not be
         proportionnal to utilization on them.
 
@@ -86,8 +88,6 @@ def filter_capacity_classes(cls, plat_info):
         """
         Filter out capacity-classes key of ``plat_info`` to remove blacklisted
         CPUs provided by:
-
-        .. automethod:: _get_blacklisted_cpus
         """
         blacklisted_cpus = set(cls._get_blacklisted_cpus(plat_info))
         return [
@@ -216,6 +216,8 @@ def get_tags(self):
     @classmethod
     def _get_rtapp_profile(cls, plat_info, cpu, freq):
         """
+        :meta public:
+
         Get a specification for a rt-app workload with the specificied duty
         cycle, pinned to the given CPU.
         """
@@ -239,6 +241,8 @@ def _get_rtapp_profile(cls, plat_info, cpu, freq):
     @classmethod
     def _from_target(cls, target: Target, *, cpu: int, freq: int, freq_list=None, res_dir: ArtifactPath = None, ftrace_coll: FtraceCollector = None) -> 'InvarianceItem':
         """
+        :meta public:
+
         :param cpu: CPU to use, or ``None`` to automatically choose an
             appropriate set of CPUs.
         :type cpu: int or None

lisa/tests/scheduler/sanity.py

@@ -40,6 +40,8 @@ def __init__(self, res_dir, plat_info, capacity_work):
     @classmethod
     def _from_target(cls, target: Target, *, res_dir: ArtifactPath = None) -> 'CapacitySanity':
         """
+        :meta public:
+
         Factory method to create a bundle using a live target
         """
         with target.cpufreq.use_governor("performance"):

lisa/trace.py

@@ -635,7 +635,7 @@ class TxtTraceParserBase(TraceParserBase):
     Mapping of event names to parser description as a dict.
 
     Each event description can include the constructor parameters of the class
-    used as :data:`DEFAULT_EVENT_PARSER_CLS`, which will be used to build event
+    used as :attr:`DEFAULT_EVENT_PARSER_CLS`, which will be used to build event
     parsers from the descriptions.
 
     If an instance of :class:`EventParserBase` is passed instead of a dict, it

lisa/wlgen/rta.py

@@ -1111,6 +1111,8 @@ def val(self):
     @classmethod
     def _from_key(cls, key, val):
         """
+        :meta public:
+
         Build an instance out of ``key`` and ``val``.
         """
         raise NotImplementedError()
@@ -1565,6 +1567,8 @@ class _SemigroupProperty(PropertyBase):
     @abc.abstractmethod
     def _SEMIGROUP_OP(x, y):
         """
+        :meta public:
+
         Function used to combine two non-None values.
         """
         pass
@@ -2112,6 +2116,8 @@ def __and__(self, other):
 
     def _and(self, other):
         """
+        :meta public:
+
         Combine together two instances by taking the non-default values for
         each attribute, and giving priority to ``self``.
         """
@@ -2186,6 +2192,8 @@ def _from_key(cls, key, val):
 
     def _and(self, other):
         """
+        :meta public:
+
         Combine clamps by taking the most constraining solution.
         """
         def none_shortcircuit(f, x, y):
@@ -3303,6 +3311,8 @@ def __init__(self, template=None, properties=None, **kwargs):
     @abc.abstractmethod
     def _make_children(cls, template, **kwargs):
         """
+        :meta public:
+
         Create a list of children :class:`RTAPhaseBase` based on the parameters
         passed from the constructor.
         """