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 import pdoc
  21 import pdoc.__main__
  22 import pdoc.markdown2
  23 import pdoc.render
  24 import pdoc.render_helpers
  25
  26 DEFAULT_ARGLIST = [
  27     '--output-directory=sdk/python',
  28     '../sdk/python/build/lib/arvados/',
  29 ]
  30 MD_EXTENSIONS = {
  31     'admonitions': None,
  32     'smarty-pants': None,
  33 }
  34
  35 def main(arglist=None):
  36     # Configure pdoc to use extras we want.
  37     pdoc.render_helpers.markdown_extensions = collections.ChainMap(
  38         pdoc.render_helpers.markdown_extensions,
  39         MD_EXTENSIONS,
  40     )
  41
  42     # Ensure markdown2 is new enough to support our desired extras.
  43     if pdoc.markdown2.__version_info__ < (2, 4, 3):
  44         print("error: need markdown2>=2.4.3 to render admonitions", file=sys.stderr)
  45         return os.EX_SOFTWARE
  46
  47     pdoc.__main__.cli(arglist)
  48     return os.EX_OK
  49
  50 if __name__ == '__main__':
  51     sys.exit(main(sys.argv[1:] or DEFAULT_ARGLIST))