20885: Add our own pdoc wrapper

Mainly to support admonitions. See the documentation and comments in
pysdk_pdoc.py for details.

Arvados-DCO-1.1-Signed-off-by: Brett Smith <brett.smith@curii.com>

diff --git a/doc/README.textile b/doc/README.textile
index 9799ac564b42237a626331c090e7d43d3711711c..47951299ccdbedd1c476908cbf21618582892a83 100644 (file)
--- a/doc/README.textile
+++ b/doc/README.textile
@@ -25,7 +25,7 @@ arvados/doc$ python3 -m venv .venv
 arvados/doc$ .venv/bin/pip install pdoc
 </pre>
 
-Then the generation process will need to be able to find @arvados/doc/.venv/bin/pdoc@. Either add that full directory to your @$PATH@, or make a @pdoc@ symlink in another directory that's already in your @$PATH@.
+Then you must activate the virtualenv (e.g., run @. .venv/bin/activate@) before you run the @bundle exec rake@ commands below.
 
 h2. Generate HTML pages
 

diff --git a/doc/Rakefile b/doc/Rakefile
index c9322bb6ae9340d1a71561338747796e2615762d..13e87167b67726c8d21ce798f19a04110ce1c4b8 100644 (file)
--- a/doc/Rakefile
+++ b/doc/Rakefile
@@ -54,11 +54,13 @@ file "sdk/python/arvados.html" do |t|
   if ENV['NO_SDK'] || File.exist?("no-sdk")
     next
   end
+  # pysdk_pdoc.py is a wrapper around the pdoc CLI. `which pdoc` is an easy
+  # and good-enough test to check whether it's installed at all.
   `which pdoc`
   if $? == 0
     raise unless system("python3", "setup.py", "build",
                         chdir: "../sdk/python", out: :err)
-    raise unless system("pdoc", "-o", "sdk/python", "../sdk/python/build/lib/arvados/",
+    raise unless system("python3", "pysdk_pdoc.py",
                         out: :err)
   else
     puts "Warning: pdoc not found, Python documentation will not be generated".colorize(:light_red)

diff --git a/doc/pysdk_pdoc.py b/doc/pysdk_pdoc.py
new file mode 100755 (executable)
index 0000000..0fe584d
--- /dev/null
+++ b/doc/pysdk_pdoc.py
@@ -0,0 +1,51 @@
+#!/usr/bin/env python3
+# Copyright (C) The Arvados Authors. All rights reserved.
+#
+# SPDX-License-Identifier: AGPL-3.0
+"""pysdk_pdoc.py - Run pdoc with extra rendering options
+
+This script is a wrapper around the standard `pdoc` tool that enables the
+`admonitions` and `smarty-pants` extras for nicer rendering. It checks that
+the version of `markdown2` included with `pdoc` supports those extras.
+
+If run without arguments, it uses arguments to build the Arvados Python SDK
+documentation.
+"""
+
+import collections
+import functools
+import os
+import sys
+
+import pdoc
+import pdoc.__main__
+import pdoc.markdown2
+import pdoc.render
+import pdoc.render_helpers
+
+DEFAULT_ARGLIST = [
+    '--output-directory=sdk/python',
+    '../sdk/python/build/lib/arvados/',
+]
+MD_EXTENSIONS = {
+    'admonitions': None,
+    'smarty-pants': None,
+}
+
+def main(arglist=None):
+    # Configure pdoc to use extras we want.
+    pdoc.render_helpers.markdown_extensions = collections.ChainMap(
+        pdoc.render_helpers.markdown_extensions,
+        MD_EXTENSIONS,
+    )
+
+    # Ensure markdown2 is new enough to support our desired extras.
+    if pdoc.markdown2.__version_info__ < (2, 4, 3):
+        print("error: need markdown2>=2.4.3 to render admonitions", file=sys.stderr)
+        return os.EX_SOFTWARE
+
+    pdoc.__main__.cli(arglist)
+    return os.EX_OK
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv[1:] or DEFAULT_ARGLIST))