doc/pysdk_pdoc.py

   1 #!/usr/bin/env python3
   2 # Copyright (C) The Arvados Authors. All rights reserved.
   3 #
   4 # SPDX-License-Identifier: AGPL-3.0
   5 """pysdk_pdoc.py - Run pdoc with extra rendering options
   6
   7 This script is a wrapper around the standard `pdoc` tool that enables the
   8 `admonitions` and `smarty-pants` extras for nicer rendering. It checks that
   9 the version of `markdown2` included with `pdoc` supports those extras.
  10
  11 If run without arguments, it uses arguments to build the Arvados Python SDK
  12 documentation.
  13 """
  14
  15 import collections
  16 import functools
  17 import os
  18 import sys
  19
  20 try:
  21     import pdoc.__main__
  22     import pdoc.markdown2
  23     import pdoc.render_helpers
  24 except ImportError as err:
  25     if __name__ == '__main__':
  26         _imp_err = err
  27     else:
  28         raise
  29 else:
  30     _imp_err = None
  31
  32 DEFAULT_ARGLIST = [
  33     '--output-directory=sdk/python',
  34     '../sdk/python/build/lib/arvados/',
  35 ]
  36 MD_EXTENSIONS = {
  37     'admonitions': None,
  38     'smarty-pants': None,
  39 }
  40
  41 def main(arglist=None):
  42     if _imp_err is not None:
  43         print("error: failed to import pdoc:", _imp_err, file=sys.stderr)
  44         return os.EX_SOFTWARE
  45     # Ensure markdown2 is new enough to support our desired extras.
  46     elif pdoc.markdown2.__version_info__ < (2, 4, 3):
  47         print("error: need markdown2>=2.4.3 to render admonitions", file=sys.stderr)
  48         return os.EX_SOFTWARE
  49
  50     # Configure pdoc to use extras we want.
  51     pdoc.render_helpers.markdown_extensions = collections.ChainMap(
  52         pdoc.render_helpers.markdown_extensions,
  53         MD_EXTENSIONS,
  54     )
  55     pdoc.__main__.cli(arglist)
  56     return os.EX_OK
  57
  58 if __name__ == '__main__':
  59     sys.exit(main(sys.argv[1:] or DEFAULT_ARGLIST))