tools/lint/perfdocs/perfdocs.py

   1 # This Source Code Form is subject to the terms of the Mozilla Public
   2 # License, v. 2.0. If a copy of the MPL was not distributed with this
   3 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
   4 import os
   5 import pathlib
   6
   7
   8 def run_perfdocs(config, logger=None, paths=None, generate=True):
   9     """
  10     Build up performance testing documentation dynamically by combining
  11     text data from YAML files that reside in `perfdoc` folders
  12     across the `testing` directory. Each directory is expected to have
  13     an `index.rst` file along with `config.yml` YAMLs defining what needs
  14     to be added to the documentation.
  15
  16     The YAML must also define the name of the "framework" that should be
  17     used in the main index.rst for the performance testing documentation.
  18
  19     The testing documentation list will be ordered alphabetically once
  20     it's produced (to avoid unwanted shifts because of unordered dicts
  21     and path searching).
  22
  23     Note that the suite name headings will be given the H4 (---) style so it
  24     is suggested that you use H3 (===) style as the heading for your
  25     test section. H5 will be used be used for individual tests within each
  26     suite.
  27
  28     Usage for verification: "./mach lint -l perfdocs ."
  29     Usage for generation: "./mach lint -l perfdocs --fix ."
  30
  31     For validation, see the Verifier class for a description of how
  32     it works.
  33
  34     The run will fail if the valid result from validate_tree is not
  35     False, implying some warning/problem was logged.
  36
  37     :param dict config: The configuration given by mozlint.
  38     :param StructuredLogger logger: The StructuredLogger instance to be used to
  39         output the linting warnings/errors.
  40     :param list paths: The paths that are being tested. Used to filter
  41         out errors from files outside of these paths.
  42     :param bool generate: If true, the docs will be (re)generated.
  43     """
  44     from perfdocs.logger import PerfDocLogger
  45
  46     if not os.environ.get("WORKSPACE", None):
  47         floc = pathlib.Path(__file__).absolute()
  48         top_dir = pathlib.Path(str(floc).split("tools")[0]).resolve()
  49     else:
  50         top_dir = pathlib.Path(os.environ.get("WORKSPACE")).resolve()
  51
  52     PerfDocLogger.LOGGER = logger
  53     PerfDocLogger.TOP_DIR = top_dir
  54
  55     # Convert all the paths to relative ones
  56     target_dir = [pathlib.Path(path) for path in paths]
  57     rel_paths = []
  58     for path in target_dir:
  59         try:
  60             rel_paths.append(path.relative_to(top_dir))
  61         except ValueError:
  62             rel_paths.append(path)
  63
  64     PerfDocLogger.PATHS = rel_paths
  65
  66     for path in target_dir:
  67         if not path.exists():
  68             raise Exception("Cannot locate directory at %s" % str(path))
  69
  70     decision_task_id = os.environ.get("DECISION_TASK_ID", None)
  71     if decision_task_id:
  72         from taskgraph.util.taskcluster import get_artifact
  73
  74         task_graph = get_artifact(decision_task_id, "public/full-task-graph.json")
  75     else:
  76         from tryselect.tasks import generate_tasks
  77
  78         task_graph = generate_tasks(
  79             params=None, full=True, disable_target_task_filter=True
  80         ).tasks
  81
  82     # Late import because logger isn't defined until later
  83     from perfdocs.generator import Generator
  84     from perfdocs.verifier import Verifier
  85
  86     # Run the verifier first
  87     verifier = Verifier(top_dir, task_graph)
  88     verifier.validate_tree()
  89
  90     if not PerfDocLogger.FAILED:
  91         # Even if the tree is valid, we need to check if the documentation
  92         # needs to be regenerated, and if it does, we throw a linting error.
  93         # `generate` dictates whether or not the documentation is generated.
  94         generator = Generator(verifier, generate=generate, workspace=top_dir)
  95         generator.generate_perfdocs()