docs/sphinx/depfile.py

   1 # coding=utf-8
   2 #
   3 # QEMU depfile generation extension
   4 #
   5 # Copyright (c) 2020 Red Hat, Inc.
   6 #
   7 # This work is licensed under the terms of the GNU GPLv2 or later.
   8 # See the COPYING file in the top-level directory.
   9
  10 """depfile is a Sphinx extension that writes a dependency file for
  11    an external build system"""
  12
  13 import os
  14 import sphinx
  15 import sys
  16 from pathlib import Path
  17
  18 __version__ = '1.0'
  19
  20 def get_infiles(env):
  21     for x in env.found_docs:
  22         yield env.doc2path(x)
  23         yield from ((os.path.join(env.srcdir, dep)
  24                     for dep in env.dependencies[x]))
  25     for mod in sys.modules.values():
  26         if hasattr(mod, '__file__'):
  27             if mod.__file__:
  28                 yield mod.__file__
  29     # this is perhaps going to include unused files:
  30     for static_path in env.config.html_static_path + env.config.templates_path:
  31         for path in Path(static_path).rglob('*'):
  32             yield str(path)
  33
  34
  35 def write_depfile(app, exception):
  36     if exception:
  37         return
  38
  39     env = app.env
  40     if not env.config.depfile:
  41         return
  42
  43     # Using a directory as the output file does not work great because
  44     # its timestamp does not necessarily change when the contents change.
  45     # So create a timestamp file.
  46     if env.config.depfile_stamp:
  47         with open(env.config.depfile_stamp, 'w') as f:
  48             pass
  49
  50     with open(env.config.depfile, 'w') as f:
  51         print((env.config.depfile_stamp or app.outdir) + ": \\", file=f)
  52         print(*get_infiles(env), file=f)
  53         for x in get_infiles(env):
  54             print(x + ":", file=f)
  55
  56
  57 def setup(app):
  58     app.add_config_value('depfile', None, 'env')
  59     app.add_config_value('depfile_stamp', None, 'env')
  60     app.connect('build-finished', write_depfile)
  61
  62     return dict(
  63         version = __version__,
  64         parallel_read_safe = True,
  65         parallel_write_safe = True
  66     )