ENH: Support __docformat__ also via command line

E.g.

    --config='docformat="numpy"'

Fixes #169

Author: kernc

pdoc/__init__.py

@@ -114,7 +114,9 @@ def _render_template(template_name, **kwargs):
         config.update((var, getattr(config_module, var, None))
                       for var in config_module.__dict__
                       if var not in MAKO_INTERNALS)
-    known_keys = set(config) | {'module', 'modules', 'http_server', 'external_links'}  # deprecated
+    known_keys = (set(config)
+                  | {'docformat'}  # Feature. https://github.com/pdoc3/pdoc/issues/169
+                  | {'module', 'modules', 'http_server', 'external_links'})  # deprecated
     invalid_keys = {k: v for k, v in kwargs.items() if k not in known_keys}
     if invalid_keys:
         warn('Unknown configuration variables (not in config.mako): {}'.format(invalid_keys))

pdoc/html_helpers.py

@@ -385,12 +385,13 @@ def handleMatch(self, m, data):
         return wrapper, m.start(0), m.end(0)
 
 
-def to_html(text: str, docformat: str = 'numpy,google', *,
+def to_html(text: str, *,
+            docformat: str = None,
             module: pdoc.Module = None, link: Callable[..., str] = None,
             latex_math: bool = False):
     """
-    Returns HTML of `text` interpreted as `docformat`.
-    By default, Numpydoc and Google-style docstrings are assumed,
+    Returns HTML of `text` interpreted as `docformat`. `__docformat__` is respected
+    if present, otherwise Numpydoc and Google-style docstrings are assumed,
     as well as pure Markdown.
 
     `module` should be the documented module (so the references can be
@@ -414,13 +415,16 @@ def to_markdown(text: str, *,
                 module: pdoc.Module = None, link: Callable[..., str] = None):
     """
     Returns `text`, assumed to be a docstring in `docformat`, converted to markdown.
+    `__docformat__` is respected
+    if present, otherwise Numpydoc and Google-style docstrings are assumed,
+    as well as pure Markdown.
 
     `module` should be the documented module (so the references can be
     resolved) and `link` is the hyperlinking function like the one in the
     example template.
     """
-    if docformat is None:
-        docformat = getattr(getattr(module, 'obj', None), '__docformat__', 'numpy,google ')
+    if not docformat:
+        docformat = str(getattr(getattr(module, 'obj', None), '__docformat__', 'numpy,google '))
         docformat, *_ = docformat.lower().split()
     if not (set(docformat.split(',')) & {'', 'numpy', 'google'}):
         warn('__docformat__ value {!r} in module {!r} not supported. '

pdoc/templates/html.mako

@@ -15,7 +15,7 @@
 
 
   def to_html(text):
-    return _to_html(text, module=module, link=link, latex_math=latex_math)
+    return _to_html(text, docformat=docformat, module=module, link=link, latex_math=latex_math)
 
 
   def get_annotation(bound_method, sep=':'):

pdoc/templates/pdf.mako

@@ -1,4 +1,4 @@
-<%!
+<%
     import re
     import pdoc
     from pdoc.html_helpers import to_markdown
@@ -10,7 +10,7 @@
         return '[{0}](#{1} "{1}")'.format(name, dobj.refname)
 
     def _to_md(text, module):
-        text = to_markdown(text, module=module, link=link)
+        text = to_markdown(text, docformat=docformat, module=module, link=link)
         # Setext H2 headings to atx H2 headings
         text = re.sub(r'\n(.+)\n-{3,}\n', r'\n## \1\n\n', text)
         # Convert admonitions into simpler paragraphs, dedent contents

pdoc/test/__init__.py

@@ -228,6 +228,12 @@ def test_html_ref_links(self):
                 ],
             )
 
+    def test_docformat(self):
+        with self.assertWarns(UserWarning) as cm,\
+                run_html(EXAMPLE_MODULE, config='docformat="restructuredtext"'):
+            self._basic_html_assertions()
+        self.assertIn('numpy', cm.warning.args[0])
+
     def test_html_no_source(self):
         with self.assertWarns(DeprecationWarning),\
                 run_html(EXAMPLE_MODULE, html_no_source=None):