bin/docs-update-generated.py

   1 #!/usr/bin/env python
   2 #
   3 # SPDX-License-Identifier: MIT
   4 #
   5 # Copyright The SCons Foundation
   6 #
   7 # Searches through the whole source tree and updates
   8 # the generated *.gen/*.mod files in the docs folder, keeping all
   9 # documentation for the tools, builders and functions...
  10 # as well as the entity declarations for them.
  11 # Uses scons-proc.py under the hood...
  12
  13 import os
  14 import sys
  15 import subprocess
  16
  17 import SConsDoc
  18
  19 # Directory where all generated files are stored
  20 gen_folder = os.path.join('doc', 'generated')
  21
  22 def argpair(key):
  23     """ Return the argument pair *.gen,*.mod for the given key. """
  24     arg = '%s,%s' % (
  25         os.path.join(gen_folder, '%s.gen' % key),
  26         os.path.join(gen_folder, '%s.mod' % key),
  27     )
  28
  29     return arg
  30
  31 def generate_all():
  32     """Generate the entity files.
  33
  34     Scan for XML files in the SCons directory and call scons-proc.py
  35     to generate the *.gen/*.mod files from it.
  36     """
  37     flist = []
  38     for path, dirs, files in os.walk('SCons'):
  39         for f in files:
  40             if f.endswith('.xml'):
  41                 fpath = os.path.join(path, f)
  42                 if SConsDoc.isSConsXml(fpath):
  43                     flist.append(fpath)
  44
  45     if flist:
  46         # Does the destination folder exist
  47         try:
  48             os.makedirs(gen_folder, exist_ok=True)
  49         except Exception:
  50             print("Couldn't create destination folder %s! Exiting..." % gen_folder, file=sys.stdout)
  51             return False
  52
  53         # Call scons-proc.py
  54         cp = subprocess.run(
  55             [
  56                 sys.executable,
  57                 os.path.join('bin', 'scons-proc.py'),
  58                 '-b', argpair('builders'),
  59                 '-f', argpair('functions'),
  60                 '-t', argpair('tools'),
  61                 '-v', argpair('variables'),
  62             ] + flist,
  63             shell=False,
  64         )
  65
  66         if cp.returncode:
  67             print("Generation failed", file=sys.stderr)
  68             return False
  69     return True
  70
  71
  72 if __name__ == "__main__":
  73     if not generate_all():
  74         sys.exit(1)