python/mozbuild/mozbuild/sphinx.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
   5 import importlib
   6 from pathlib import Path
   7
   8 from docutils import nodes
   9 from docutils.parsers.rst import Directive
  10 from mots.config import FileConfig
  11 from mots.directory import Directory
  12 from mots.export import export_to_format
  13 from sphinx.util.docstrings import prepare_docstring
  14 from sphinx.util.docutils import ReferenceRole
  15
  16
  17 def function_reference(f, attr, args, doc):
  18     lines = []
  19
  20     lines.extend(
  21         [
  22             f,
  23             "-" * len(f),
  24             "",
  25         ]
  26     )
  27
  28     docstring = prepare_docstring(doc)
  29
  30     lines.extend(
  31         [
  32             docstring[0],
  33             "",
  34         ]
  35     )
  36
  37     arg_types = []
  38
  39     for t in args:
  40         if isinstance(t, list):
  41             inner_types = [t2.__name__ for t2 in t]
  42             arg_types.append(" | ".join(inner_types))
  43             continue
  44
  45         arg_types.append(t.__name__)
  46
  47     arg_s = "(%s)" % ", ".join(arg_types)
  48
  49     lines.extend(
  50         [
  51             ":Arguments: %s" % arg_s,
  52             "",
  53         ]
  54     )
  55
  56     lines.extend(docstring[1:])
  57     lines.append("")
  58
  59     return lines
  60
  61
  62 def variable_reference(v, st_type, in_type, doc):
  63     lines = [
  64         v,
  65         "-" * len(v),
  66         "",
  67     ]
  68
  69     docstring = prepare_docstring(doc)
  70
  71     lines.extend(
  72         [
  73             docstring[0],
  74             "",
  75         ]
  76     )
  77
  78     lines.extend(
  79         [
  80             ":Storage Type: ``%s``" % st_type.__name__,
  81             ":Input Type: ``%s``" % in_type.__name__,
  82             "",
  83         ]
  84     )
  85
  86     lines.extend(docstring[1:])
  87     lines.append("")
  88
  89     return lines
  90
  91
  92 def special_reference(v, func, typ, doc):
  93     lines = [
  94         v,
  95         "-" * len(v),
  96         "",
  97     ]
  98
  99     docstring = prepare_docstring(doc)
 100
 101     lines.extend(
 102         [
 103             docstring[0],
 104             "",
 105             ":Type: ``%s``" % typ.__name__,
 106             "",
 107         ]
 108     )
 109
 110     lines.extend(docstring[1:])
 111     lines.append("")
 112
 113     return lines
 114
 115
 116 def format_module(m):
 117     lines = []
 118
 119     lines.extend(
 120         [
 121             ".. note::",
 122             "   moz.build files' implementation includes a ``Path`` class.",
 123         ]
 124     )
 125     path_docstring_minus_summary = prepare_docstring(m.Path.__doc__)[2:]
 126     lines.extend(["   " + line for line in path_docstring_minus_summary])
 127
 128     for subcontext, cls in sorted(m.SUBCONTEXTS.items()):
 129         lines.extend(
 130             [
 131                 ".. _mozbuild_subcontext_%s:" % subcontext,
 132                 "",
 133                 "Sub-Context: %s" % subcontext,
 134                 "=============" + "=" * len(subcontext),
 135                 "",
 136             ]
 137         )
 138         lines.extend(prepare_docstring(cls.__doc__))
 139         if lines[-1]:
 140             lines.append("")
 141
 142         for k, v in sorted(cls.VARIABLES.items()):
 143             lines.extend(variable_reference(k, *v))
 144
 145     lines.extend(
 146         [
 147             "Variables",
 148             "=========",
 149             "",
 150         ]
 151     )
 152
 153     for v in sorted(m.VARIABLES):
 154         lines.extend(variable_reference(v, *m.VARIABLES[v]))
 155
 156     lines.extend(
 157         [
 158             "Functions",
 159             "=========",
 160             "",
 161         ]
 162     )
 163
 164     for func in sorted(m.FUNCTIONS):
 165         lines.extend(function_reference(func, *m.FUNCTIONS[func]))
 166
 167     lines.extend(
 168         [
 169             "Special Variables",
 170             "=================",
 171             "",
 172         ]
 173     )
 174
 175     for v in sorted(m.SPECIAL_VARIABLES):
 176         lines.extend(special_reference(v, *m.SPECIAL_VARIABLES[v]))
 177
 178     return lines
 179
 180
 181 def find_mots_config_path(app):
 182     """Find and return mots config path if it exists."""
 183     base_path = Path(app.srcdir).parent
 184     config_path = base_path / "mots.yaml"
 185     if config_path.exists():
 186         return config_path
 187
 188
 189 def export_mots(config_path):
 190     """Load mots configuration and export it to file."""
 191     # Load from disk and initialize configuration and directory.
 192     config = FileConfig(config_path)
 193     config.load()
 194     directory = Directory(config)
 195     directory.load()
 196
 197     # Fetch file format (i.e., "rst") and export path.
 198     frmt = config.config["export"]["format"]
 199     path = config_path.parent / config.config["export"]["path"]
 200
 201     # Generate output.
 202     output = export_to_format(directory, frmt)
 203
 204     # Create export directory if it does not exist.
 205     path.parent.mkdir(parents=True, exist_ok=True)
 206
 207     # Write changes to disk.
 208     with path.open("w", encoding="utf-8") as f:
 209         f.write(output)
 210
 211
 212 class MozbuildSymbols(Directive):
 213     """Directive to insert mozbuild sandbox symbol information."""
 214
 215     required_arguments = 1
 216
 217     def run(self):
 218         module = importlib.import_module(self.arguments[0])
 219         fname = module.__file__
 220         if fname.endswith(".pyc"):
 221             fname = fname[0:-1]
 222
 223         self.state.document.settings.record_dependencies.add(fname)
 224
 225         # We simply format out the documentation as rst then feed it back
 226         # into the parser for conversion. We don't even emit ourselves, so
 227         # there's no record of us.
 228         self.state_machine.insert_input(format_module(module), fname)
 229
 230         return []
 231
 232
 233 class Searchfox(ReferenceRole):
 234     """Role which links a relative path from the source to it's searchfox URL.
 235
 236     Can be used like:
 237
 238         See :searchfox:`browser/base/content/browser-places.js` for more details.
 239
 240     Will generate a link to
 241     ``https://searchfox.org/mozilla-central/source/browser/base/content/browser-places.js``
 242
 243     The example above will use the path as the text, to use custom text:
 244
 245         See :searchfox:`this file <browser/base/content/browser-places.js>` for
 246         more details.
 247
 248     To specify a different source tree:
 249
 250         See :searchfox:`mozilla-beta:browser/base/content/browser-places.js`
 251         for more details.
 252     """
 253
 254     def run(self):
 255         base = "https://searchfox.org/{source}/source/{path}"
 256
 257         if ":" in self.target:
 258             source, path = self.target.split(":", 1)
 259         else:
 260             source = "mozilla-central"
 261             path = self.target
 262
 263         url = base.format(source=source, path=path)
 264
 265         if self.has_explicit_title:
 266             title = self.title
 267         else:
 268             title = path
 269
 270         node = nodes.reference(self.rawtext, title, refuri=url, **self.options)
 271         return [node], []
 272
 273
 274 def setup(app):
 275     from moztreedocs import manager
 276
 277     app.add_directive("mozbuildsymbols", MozbuildSymbols)
 278     app.add_role("searchfox", Searchfox())
 279
 280     # Unlike typical Sphinx installs, our documentation is assembled from
 281     # many sources and staged in a common location. This arguably isn't a best
 282     # practice, but it was the easiest to implement at the time.
 283     #
 284     # Here, we invoke our custom code for staging/generating all our
 285     # documentation.
 286
 287     # Export and write "governance" documentation to disk.
 288     config_path = find_mots_config_path(app)
 289     if config_path:
 290         export_mots(config_path)
 291
 292     manager.generate_docs(app)
 293     app.srcdir = manager.staging_dir