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     # Because the module is prviate, pdoc does not build documentation for any
  36     # of it. The exclusion below additionally prevents pdoc from hyperlinking
  37     # references under arvados._internal that appear in method signatures, etc.
  38     '!arvados._internal',
  39 ]
  40 MD_EXTENSIONS = {
  41     'admonitions': None,
  42     'smarty-pants': None,
  43 }
  44
  45 def main(arglist=None):
  46     if _imp_err is not None:
  47         print("error: failed to import pdoc:", _imp_err, file=sys.stderr)
  48         return os.EX_SOFTWARE
  49     # Ensure markdown2 is new enough to support our desired extras.
  50     elif pdoc.markdown2.__version_info__ < (2, 4, 3):
  51         print("error: need markdown2>=2.4.3 to render admonitions", file=sys.stderr)
  52         return os.EX_SOFTWARE
  53
  54     # Configure pdoc to use extras we want.
  55     pdoc.render_helpers.markdown_extensions = collections.ChainMap(
  56         pdoc.render_helpers.markdown_extensions,
  57         MD_EXTENSIONS,
  58     )
  59     pdoc.__main__.cli(arglist)
  60     return os.EX_OK
  61
  62 if __name__ == '__main__':
  63     sys.exit(main(sys.argv[1:] or DEFAULT_ARGLIST))