Merge remote-tracking branch 'richtja/sphinx_fix'

Signed-off-by: Cleber Rosa <[email protected]>

.readthedocs.yaml

@@ -14,6 +14,7 @@ build:
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
   configuration: docs/source/conf.py
+  fail_on_warning: true
 
 # We recommend specifying your dependencies to enable reproducible builds:
 # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html

avocado/core/dispatcher.py

@@ -29,7 +29,7 @@
 def get_dispatchers(module_name):
     """Returns the classes that implement plugin dispatching
 
-    These should inherit from the *ExtensionManager base classes
+    These should inherit from the *ExtensionManager* base classes
     and contain suitable descriptions.
 
     The produced values are tuples that contain the dispatcher class

avocado/core/plugin_interfaces.py

@@ -194,7 +194,7 @@ def post_test_runnables(self, test_runnable, suite_config=None):
         :param suite_config: Configuration dict relevant for the whole suite.
         :return: PostTest task runnables created by plugin.
         :rtype: list of tuple(:class:`avocado.core.nrunner.Runnable`,
-        `avocado.core.task.runtime.RuntimeTask.possible_dependency_results`)
+                `avocado.core.task.runtime.RuntimeTask.possible_dependency_results`)
         """
 
 

avocado/core/task/runtime.py

@@ -63,7 +63,8 @@ def from_runnable(
                        make into the job's results.
         :type job_id: str
         :param satisfiable_deps_execution_statuses: The dependency result types that
-        satisfy the execution of this RuntimeTask.
+                                                    satisfy the execution of this
+                                                    RuntimeTask.
         :type satisfiable_deps_execution_statuses: list of test results.
         :returns: RuntimeTask of the test from runnable
         """
@@ -111,7 +112,8 @@ def __init__(self, task, satisfiable_deps_execution_statuses=None):
         :param task: The task to keep additional information about
         :type task: :class:`avocado.core.nrunner.Task`
         :param satisfiable_deps_execution_statuses: The dependency result types that
-        satisfy the execution of this RuntimeTask.
+                                                    satisfy the execution of this
+                                                    RuntimeTask.
         :type satisfiable_deps_execution_statuses: list of test results.
         """
         #: The :class:`avocado.core.nrunner.Task`

avocado/core/utils/messages.py

@@ -65,8 +65,8 @@ def get(
         """Creates finished message with all necessary information.
 
         :param result: test result
-        :type result values for the statuses defined in
-                     :class: avocado.core.teststatus.STATUSES
+        :type result: values for the statuses defined in
+                      :class: avocado.core.teststatus.STATUSES
         :param fail_reason: parameter for brief specification, of the failed
                             result.
         :type fail_reason: str

avocado/utils/cpu.py

@@ -514,9 +514,10 @@ def get_numa_node_has_cpus():
     Get the list NUMA node numbers which has CPU's on the system,
     if there is no CPU associated to NUMA node,Those NUMA node number
     will not be appended to list.
+
     :return: A list where NUMA node numbers only which has
              CPU's - as elements of The list.
-    :rtype : List
+    :rtype: List
     """
     cpu_path = "/sys/devices/system/node/has_cpu"
     delim = ",", "-"
@@ -529,9 +530,10 @@ def get_numa_node_has_cpus():
 def numa_nodes_with_assigned_cpus():
     """
     Get NUMA nodes with associated CPU's on the system.
+
     :return: A dictionary,in which "NUMA node numbers" as key
              and "NUMA node associated CPU's" as values.
-    :rtype : dictionary
+    :rtype: dictionary
     """
     numa_nodes_with_cpus = {}
     for path in glob.glob("/sys/devices/system/node/node[0-9]*"):

avocado/utils/external/gdbmi_parser.py

@@ -104,7 +104,8 @@ def t_whitespace(self, s):  # pylint: disable=W0613
         r"[ \t\f\v]+"
 
     def t_symbol(self, s):
-        r",|\{|\}|\[|\]|\="
+        """"""  # pylint: disable=C0112
+        r",|\{|\}|\[|\]|\="  # pylint: disable=w0105
         self.rv.append(Token(s, s))
 
     def t_result_type(self, s):

avocado/utils/network/interfaces.py

@@ -716,7 +716,7 @@ def netmask_to_cidr(self, netmask):
         255.255.252.0 = 22
 
         :param netmask: Netmask value example 255.255.255.0
-        :return : Returns mask value of given netmask
+        :return: Returns mask value of given netmask
         """
         return sum(bin(int(bits)).count("1") for bits in netmask.split("."))
 
@@ -796,9 +796,9 @@ def ping_flood(self, int_name, peer_ip, ping_count):
         :param int_name: source interface name.
         :param peer_ip: Peer IP address (IPv4 or IPv6)
         :param ping_count: How many ICMP echo packets to send.
-        :return : returns True on successful ping flood.
+        :return: returns True on successful ping flood.
                   returns False on ping flood failure.
-        :rtype : boolean
+        :rtype: boolean
         """
         cmd = f"ping -I {int_name} {peer_ip} -c {ping_count} -f "
         ping_process = subprocess.Popen(

avocado/utils/pci.py

@@ -326,7 +326,7 @@ def unbind(driver, full_pci_address):
 
     :param driver: driver of the PCI address (full_pci_address)
     :param full_pci_address:  Full PCI address including domain (0000:03:00.0)
-    return: None
+    :return: None
     """
     genio.write_file_or_fail(f"/sys/bus/pci/drivers/{driver}/unbind", full_pci_address)
     if wait.wait_for(
@@ -345,7 +345,7 @@ def bind(driver, full_pci_address):
 
     :param driver: driver of the PCI address (full_pci_address)
     :param full_pci_address:  Full PCI address including domain (0000:03:00.0)
-    return: None
+    :return: None
     """
     genio.write_file_or_fail(f"/sys/bus/pci/drivers/{driver}/bind", full_pci_address)
     if not wait.wait_for(
@@ -363,8 +363,8 @@ def get_vendor_id(full_pci_address):
     Get vendor id of a PCI address
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: vendor id of PCI address
-    rtype: str
+    :return: vendor id of PCI address
+    :rtype: str
     """
     cmd = f"lspci -n -s {full_pci_address}"
     out = process.run(cmd, ignore_status=True, shell=True).stdout_text
@@ -378,8 +378,8 @@ def reset_check(full_pci_address):
     Check if reset for "full_pci_address" is successful
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: whether reset for "full_pci_address" is successful
-    rtype: bool
+    :return: whether reset for "full_pci_address" is successful
+    :rtype: bool
     """
     cmd = f"lspci -vvs {full_pci_address}"
     output = process.run(cmd, ignore_status=True, shell=True).stdout_text
@@ -393,8 +393,8 @@ def rescan_check(full_pci_address):
     Check if rescan for full_pci_address is successful
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: whether rescan for full_pci_address is successful
-    rtype: bool
+    :return: whether rescan for full_pci_address is successful
+    :rtype: bool
     """
     cmd = f"lspci -vvs {full_pci_address}"
     output = process.run(cmd, ignore_status=True, shell=True).stdout_text
@@ -410,8 +410,8 @@ def change_domain_check(dom, full_pci_address, def_dom):
     :param dom: domain type
     :param def_dom: default domain of pci device(full_pci_address)
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: whether domain changed successfully to "dom"
-    rtype: bool
+    :return: whether domain changed successfully to "dom"
+    :rtype: bool
     """
     try:
         output = genio.read_one_line(
@@ -430,7 +430,7 @@ def reset(full_pci_address):
     Remove the full_pci_address
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: None
+    :return: None
     """
     genio.write_file_or_fail(f"/sys/bus/pci/devices/{full_pci_address}/remove", "1")
     if not wait.wait_for(lambda: reset_check(full_pci_address), timeout=5):
@@ -442,7 +442,7 @@ def rescan(full_pci_address):
     Rescan the system and check for full_pci_address
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: None
+    :return: None
     """
     genio.write_file_or_fail("/sys/bus/pci/rescan", "1")
     if not wait.wait_for(lambda: rescan_check(full_pci_address), timeout=5):
@@ -454,8 +454,8 @@ def get_iommu_group(full_pci_address):
     Return the iommu group of full_pci_address
 
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: iommu group of full_pci_address
-    rtype: string
+    :return: iommu group of full_pci_address
+    :rtype: string
     """
     cmd = f"lspci -vvvv -s {full_pci_address}"
     out = process.run(cmd, ignore_status=True, shell=True)
@@ -472,7 +472,7 @@ def change_domain(dom, def_dom, full_pci_address):
     :param dom: domain type
     :param def_dom: default domain of pci device(full_pci_address)
     :param full_pci_address: Full PCI address including domain (0000:03:00.0)
-    return: None
+    :return: None
     """
     genio.write_file_or_fail(
         f"/sys/bus/pci/devices/{full_pci_address}/iommu_group/type", dom

avocado/utils/podman.py

@@ -44,7 +44,7 @@ def __init__(self, podman_bin=None):
     async def execute(self, *args):
         """Execute a command and return the returncode, stdout and stderr.
 
-        :param *args: Variable length argument list to be used as argument
+        :param args: Variable length argument list to be used as argument
                       during execution.
         :rtype: tuple with returncode, stdout and stderr.
         """

avocado/utils/software_manager/backends/rpm.py

@@ -185,7 +185,7 @@ def prepare_source(spec_file, dest_path=None, build_option=None):
         Rpmbuild the spec path and return build dir
 
         :param spec_path: spec path to install
-        :param  build_option : rpmbuild option
+        :param  build_option: rpmbuild option
         :return path: build directory
         """
 

avocado/utils/software_manager/backends/yum.py

@@ -245,7 +245,7 @@ def get_source(self, name, dest_path, build_option=None):
 
         :param name: name of the package
         :param dest_path: destination_path
-        :param  build_option : rpmbuild option
+        :param  build_option: rpmbuild option
 
         :return final_dir: path of ready-to-build directory
         """

avocado/utils/software_manager/backends/zypper.py

@@ -174,7 +174,7 @@ def get_source(self, name, dest_path, build_option=None):
 
         :param name: name of the package
         :param dest_path: destination_path
-        :param  build_option : rpmbuild option
+        :param  build_option: rpmbuild option
 
         :return final_dir: path of ready-to-build directory
         """

docs/source/blueprints/BP003.rst

@@ -544,7 +544,7 @@ scheduler".  They are provided for discussion only and do not
 constitute hard requirements for this or future work.
 
 Tasks' requirements fulfillment
-------------------------------
+-------------------------------
 
 1. Prepare for the execution of a task, such as the fulfillment of extra task
 requirements. The requirements resolver is one, if not the only way,

docs/source/blueprints/BP005.rst

@@ -202,11 +202,11 @@ potential need for a new release:
 * If the number of commits since last release has reached a threshold; AND
 * There is no open discussion with the tag “release-decision”:
   * Creates a new discussion (with the "release-decision" tag) to run a poll
-    between all the MAINTAINERS, so they will have the opportunity to thumbs
-    up if there is a need for a new release;
+  between all the MAINTAINERS, so they will have the opportunity to thumbs
+  up if there is a need for a new release;
   * The link to the new discussion should be sent to all MAINTAINERS;
   * If the decision is positive, a round-robin selected maintainer should be
-    responsible for coordinating the release it self;
+  responsible for coordinating the release it self;
   * And the discussion should be closed
 * If there is any existing open discussion, the bot job should comment on the
   same discussion with the updated list of commits and ping again the

docs/source/blueprints/template.rst

@@ -1,8 +1,10 @@
+:orphan:
+
 BP???
 #####
 
 .. Please refer to BP000 for detailed instructions on how to write a
-   BluePrint (and remove this comment from your final document).
+   BluePrint (and remove this comment and :orphan: tag from your final document).
 
 :Number: BP???
 :Title:

docs/source/conf.py

@@ -40,8 +40,9 @@ def generate_reference():
     reference_path = os.path.join(
         ROOT_PATH, "docs", "source", "config", "reference.rst"
     )
+    stdout_text = result.stdout_text.replace("['/run/*']", r"['/run/\*']")
     with open(reference_path, "w", encoding="utf-8") as reference:
-        reference.write(result.stdout_text)
+        reference.write(stdout_text)
 
 
 def generate_vmimage_distro():
@@ -202,7 +203,7 @@ def generate_vmimage_distro():
             continue
         output_dir = os.path.join(API_OPTIONAL_PLUGINS_PATH, name)
         params = {"API_SOURCE_DIR": path, "output_dir": output_dir, "exclude_dirs": ""}
-        process.run(APIDOC_TEMPLATE % params)
+        process.run(f"{APIDOC_TEMPLATE % params} --implicit-namespaces")
         # Remove the unnecessary generated files
         os.unlink(os.path.join(output_dir, "modules.rst"))
         optional_plugins_toc.write(f"\n   {os.path.join(name, name)}")
@@ -262,6 +263,6 @@ def generate_vmimage_distro():
     ),
 ]
 
-intersphinx_mapping = {"http://docs.python.org/": None}  # pylint: disable=C0103
+intersphinx_mapping = {"python": ("https://docs.python.org", None)}
 
 autoclass_content = "both"  # pylint: disable=C0103

docs/source/guides/contributor/chapters/plugins.rst

@@ -197,6 +197,7 @@ NORMAL (50). For easier usage, avocado has predefined
 values in: 
 
 .. autoclass:: avocado.core.extension_manager.PluginPriority
+   :noindex:
    :members:
    :undoc-members:
 

docs/source/guides/reference/chapters/runners.rst

@@ -536,20 +536,27 @@ Supported message types
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 .. autoclass:: avocado.core.messages.StartMessageHandler
+   :noindex:
 
 .. autoclass:: avocado.core.messages.FinishMessageHandler
+   :noindex:
 
 Running messages
 ++++++++++++++++
 This message can be used during the run-time and has different properties
 based on the information which is being transmitted.
 
 .. autoclass:: avocado.core.messages.LogMessageHandler
+   :noindex:
 
 .. autoclass:: avocado.core.messages.StdoutMessageHandler
+   :noindex:
 
 .. autoclass:: avocado.core.messages.StderrMessageHandler
+   :noindex:
 
 .. autoclass:: avocado.core.messages.WhiteboardMessageHandler
+   :noindex:
 
 .. autoclass:: avocado.core.messages.FileMessageHandler
+   :noindex:

docs/source/guides/writer/chapters/writing.rst

@@ -1310,7 +1310,7 @@ tests:
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_BASEDIR        | Base directory of Avocado tests       | $HOME/src/avocado/avocado.dev/examples/tests                                                        |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                              |
+| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                               |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TESTS_COMMON_TMPDIR | Temporary directory created by the    | /var/tmp/avocado_cp07qzd9                                                                           |
 |                             | :ref:`plugin_teststmpdir` plugin.  The|                                                                                                     |
@@ -1336,7 +1336,7 @@ tests:
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TEST_BASEDIR        | Base directory of Avocado tests       | $HOME/src/avocado/avocado.dev/examples/tests                                                        |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
-| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                              |
+| AVOCADO_TEST_WORKDIR        | Work directory for the test           | /var/tmp/.avocado-taskcx8of8di/test-results/tmp_dirfgqrnbu/1-Env.test                               |
 +-----------------------------+---------------------------------------+-----------------------------------------------------------------------------------------------------+
 | AVOCADO_TESTS_COMMON_TMPDIR | Temporary directory created by the    | /var/tmp/avocado_XhEdo/                                                                             |
 |                             | :ref:`plugin_teststmpdir` plugin.  The|                                                                                                     |

docs/source/plugins/index.rst

@@ -34,6 +34,3 @@ Some of these plugins may have extra dependencies of their own.
    optional/results/index
    optional/robot
    optional/varianters/index
-   optional/varianter_pict
-   optional/multiplexer
-   optional/varianter_yaml_to_mux

docs/source/releases/53_0.rst

@@ -18,7 +18,7 @@ Users/Test Writers
   input used for the varianter yaml_to_mux plugin.  It allows the
   definition of test suite based on a YAML file, including different
   variants for different tests.  For more information refer to
-  :ref:`yaml_loader`.
+  `yaml_loader`.
 
 * A better handling of interruption related signals, such as
   ``SIGINT`` and ``SIGTERM``.  Avocado will now try harder to not