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 from pathlib import Path
  21
  22 try:
  23     import pdoc.__main__
  24     import pdoc.markdown2
  25     import pdoc.render_helpers
  26 except ImportError as err:
  27     if __name__ == '__main__':
  28         _imp_err = err
  29     else:
  30         raise
  31 else:
  32     _imp_err = None
  33
  34 try:
  35     import arvados
  36 except ImportError:
  37     DEFAULT_ARGLIST = []
  38 else:
  39     DEFAULT_ARGLIST = [
  40         '--output-directory=sdk/python',
  41         str(Path(arvados.__file__).parent),
  42         # Because the module is prviate, pdoc does not build documentation for any
  43         # of it. The exclusion below additionally prevents pdoc from hyperlinking
  44         # references under arvados._internal that appear in method signatures, etc.
  45         '!arvados._internal',
  46     ]
  47
  48 MD_EXTENSIONS = {
  49     'admonitions': None,
  50     'smarty-pants': None,
  51 }
  52
  53 def main(arglist=None):
  54     if _imp_err is not None:
  55         print("error: failed to import pdoc:", _imp_err, file=sys.stderr)
  56         return os.EX_SOFTWARE
  57     # Ensure markdown2 is new enough to support our desired extras.
  58     elif pdoc.markdown2.__version_info__ < (2, 4, 3):
  59         print("error: need markdown2>=2.4.3 to render admonitions", file=sys.stderr)
  60         return os.EX_SOFTWARE
  61
  62     # Configure pdoc to use extras we want.
  63     pdoc.render_helpers.markdown_extensions = collections.ChainMap(
  64         pdoc.render_helpers.markdown_extensions,
  65         MD_EXTENSIONS,
  66     )
  67     pdoc.__main__.cli(arglist)
  68     return os.EX_OK
  69
  70 if __name__ == '__main__':
  71     sys.exit(main(sys.argv[1:] or DEFAULT_ARGLIST))