Added '--markup' option.

pdoc/cli.py

@@ -9,6 +9,7 @@
 import pdoc.static
 import pdoc.version
 import pdoc.web
+import pdoc.markup
 
 parser = argparse.ArgumentParser(
     description="Automatically generate API docs for Python modules.",
@@ -99,7 +100,22 @@
     default=8080,
     help="The port on which to run the HTTP server.",
 )
+aa(
+    "--style",
+    type=str,
+    choices=['pre', 'markdown'],
+    default='markdown',
+    help='''
+        The style of docstrings. Docstrings are converted to HTML as this option.
+        "markdown" is Markdown (Default).
+        "pre" does not convert docstrings and just wrappd <pre>...</pre>.
+    ''',
+)
 
+Markups = {
+    'markdown': pdoc.markup.Markdown(),
+    'pre': pdoc.markup.Pre(),
+}
 
 def _eprint(*args, **kwargs):
     kwargs["file"] = sys.stderr
@@ -139,6 +155,8 @@ def docfilter(o):
         args.overwrite = True
         args.link_prefix = "/"
 
+    args.markup = Markups[args.markup]
+
     if args.http:
         # Run the HTTP server.
         httpd = pdoc.web.DocServer((args.http_host, args.http_port), args, roots)
@@ -153,7 +171,7 @@ def docfilter(o):
         if not args.overwrite and pdoc.static.would_overwrite(dst, roots):
             _eprint("Rendering would overwrite files, but --overwite is not set")
             sys.exit(1)
-        pdoc.static.html_out(dst, roots)
+        pdoc.static.html_out(dst, roots, args.markup)
     else:
         # Plain text
         for m in roots:

pdoc/html_helpers.py

@@ -61,15 +61,11 @@ def linkify(parent, match, link_prefix):
     return "[`%s`](%s)" % (name, url)
 
 
-def mark(s, module_list=None, linky=True):
-    if linky:
-        s, _ = re.subn("\b\n\b", " ", s)
-    # if not module_list:
-    #     s, _ = re.subn("`[^`]+`", linkify, s)
-
-    extensions = ["fenced-code-blocks"]
-    s = markdown2.markdown(s.strip(), extras=extensions)
-    return s
+def mark(markup):
+    def _mark(s):
+        s = markup.convert(s)
+        return '<div class="%s">%s</div>' % (markup.css_class(), s)
+    return _mark
 
 
 def glimpse(s, length=100):

pdoc/markup.py

@@ -0,0 +1,23 @@
+import markdown2
+from abc import abstractmethod
+
+class Markup:
+    @abstractmethod
+    def compile(self, source: str) -> str:
+        pass
+
+
+class Markdown(Markup):
+    def convert(self, source: str) -> str:
+        return markdown2.markdown(source.strip(), extras=["fenced-code-blocks"])
+
+    def css_class(self) -> str:
+        return 'markup-markdown'
+
+
+class Pre(Markup):
+    def convert(self, source: str) -> str:
+        return '<pre>' + source + '</pre>'
+
+    def css_class(self) -> str:
+        return 'markup-pre'

pdoc/render.py

@@ -6,6 +6,7 @@
 from mako.exceptions import TopLevelLookupException
 
 import pdoc.doc
+import pdoc.markup
 
 
 html_module_suffix = ".m.html"
@@ -50,20 +51,25 @@ def _get_tpl(name):
     return t
 
 
-def html_index(roots: typing.Sequence[pdoc.doc.Module], link_prefix: str = "/") -> str:
+def html_index(
+    roots: typing.Sequence[pdoc.doc.Module],
+    link_prefix: str,
+    markup: pdoc.markup.Markup,
+) -> str:
     """
         Render an HTML module index.
     """
     t = _get_tpl("/html_index.mako")
-    t = t.render(roots=roots, link_prefix=link_prefix)
+    t = t.render(roots=roots, link_prefix=link_prefix, markup=markup)
     return t.strip()
 
 
 def html_module(
-    mod: pdoc.doc.Module,
-    external_links: bool = False,
-    link_prefix: str = "/",
-    source: bool = True,
+    module: pdoc.doc.Module,
+    external_links: bool,
+    link_prefix: str,
+    source: bool,
+    markup: pdoc.markup.Markup,
 ) -> str:
     """
     Returns the documentation for the module `module_name` in HTML
@@ -91,10 +97,11 @@ def html_module(
     """
     t = _get_tpl("/html_module.mako")
     t = t.render(
-        module=mod,
+        module=module,
         external_links=external_links,
         link_prefix=link_prefix,
         show_source_code=source,
+        markup=markup,
     )
     return t.strip()
 

pdoc/static.py

@@ -63,19 +63,27 @@ def would_overwrite(dst: pathlib.Path, roots: typing.Sequence[pdoc.doc.Module])
 def html_out(
     dst: pathlib.Path,
     roots: typing.Sequence[pdoc.doc.Module],
-    external_links: bool = True,
-    link_prefix: str = "",
-    source: bool = False,
+    markup: pdoc.markup.Markup,
 ):
+    link_prefix = ''
+
     if len(roots) > 1:
         p = dst / "index.html"
-        idx = pdoc.render.html_index(roots, link_prefix=link_prefix)
+        idx = pdoc.render.html_index(
+            roots,
+            link_prefix=link_prefix,
+            markup = markup,
+        )
         p.write_text(idx, encoding="utf-8")
     for root in roots:
         for m in root.allmodules():
             p = dst.joinpath(module_to_path(m))
             p.parent.mkdir(parents=True, exist_ok=True)
             out = pdoc.render.html_module(
-                m, external_links=external_links, link_prefix=link_prefix, source=source
+                module=m,
+                external_links = True,
+                link_prefix = link_prefix,
+                source= False,
+                markup = markup,
             )
             p.write_text(out, encoding="utf-8")

pdoc/templates/css.mako

@@ -252,6 +252,15 @@
   .desc h1, .desc h2, .desc h3 {
     font-size: 100% !important;
   }
+
+  .markup-pre pre {
+    background: inherit;
+    border: none;
+    box-shadow: none;
+    margin: 0;
+    padding: 0;
+  }
+
   .clear {
     clear: both;
   }

pdoc/templates/html_index.mako

@@ -8,14 +8,14 @@ import pdoc.html_helpers as hh
 <%inherit file="html_frame.mako"/>
 
 <%def name="show_module_list(roots)">
-<h1>Python module list</h1>
+  <h1>Python module list</h1>
   <table id="module-list">
   % for root in roots:
     <tr>
       <td><a href="${link_prefix}${root.name}">${root.name}</a></td>
       <td>
       % if len(root.docstring.strip()) > 0:
-        <div class="desc">${root.docstring | hh.mark}</div>
+        <div class="desc}">${root.docstring | hh.mark(markup)}</div>
       % endif
       </td>
     </tr>

pdoc/templates/html_module.mako

@@ -27,9 +27,9 @@ import pdoc.html_helpers as hh
   %>
   % if len(docstring) > 0:
   % if inherits:
-    <div class="desc inherited">${docstring | hh.mark}</div>
+    <div class="desc inherited">${docstring | hh.mark(markup)}</div>
   % else:
-    <div class="desc">${docstring | hh.mark}</div>
+    <div class="desc">${docstring | hh.mark(markup)}</div>
   % endif
   % endif
   % if not isinstance(d, pdoc.doc.Module):
@@ -89,7 +89,7 @@ import pdoc.html_helpers as hh
 
   <header id="section-intro">
   <h1 class="title"><span class="name">${module.name}</span> module</h1>
-  ${module.docstring | hh.mark}
+  ${module.docstring | hh.mark(markup)}
   ${show_source(module)}
   </header>
 

pdoc/web.py

@@ -23,11 +23,12 @@ def do_HEAD(self):
 
     def do_GET(self):
         if self.path == "/":
-            midx = []
-            for m in self.server.modules:
-                midx.append((m.name, m.docstring))
-            midx = sorted(midx, key=lambda x: x[0].lower())
-            out = pdoc.render.html_index(midx, self.server.args.link_prefix)
+            midx = sorted(self.server.modules, key=lambda x: x.name.lower())
+            out = pdoc.render.html_index(
+                midx,
+                self.server.args.link_prefix,
+                self.server.args.markup,
+            )
         elif self.path.endswith(".ext"):
             # External links are a bit weird. You should view them as a giant
             # hack. Basically, the idea is to "guess" where something lives
@@ -91,7 +92,15 @@ def html(self):
         # Deny favico shortcut early.
         if self.path == "/favicon.ico":
             return None
-        return pdoc.render.html_module(pdoc.extract.extract_module(self.import_path))
+
+        module = pdoc.extract.extract_module(self.import_path)
+        return pdoc.render.html_module(
+            module=module,
+            external_links= False,
+            link_prefix= "/",
+            source=True,        
+            markup=self.server.args.markup,
+        )
 
     def resolve_ext(self, import_path):
         def exists(p):

test/test_render.py

@@ -1,14 +1,16 @@
 import pdoc.extract
 import pdoc.render
 import pdoc.doc
+import pdoc.markup
 
 import tutils
 
 
 def test_html_module():
     with tutils.tdir():
+        markup = pdoc.markup.Markdown()
         m = pdoc.extract.extract_module("./modules/one")
-        assert pdoc.render.html_module(m)
+        assert pdoc.render.html_module(m, False, '/', False, markup)
 
 
 def test_html_module_index():
@@ -17,4 +19,5 @@ def test_html_module_index():
             pdoc.extract.extract_module("./modules/one"),
             pdoc.extract.extract_module("./modules/submods")
         ]
-        assert pdoc.render.html_index(roots)
+        markup = pdoc.markup.Markdown()
+        assert pdoc.render.html_index(roots, markup)

test/test_static.py

@@ -45,11 +45,12 @@ def test_static(tmpdir):
     with tutils.tdir():
         one = pdoc.extract.extract_module("./modules/one")
         two = pdoc.extract.extract_module("./modules/submods")
+        markup = pdoc.markup.Markdown()
         assert not pdoc.static.would_overwrite(dst, [one])
         assert not pdoc.static.would_overwrite(dst, [one, two])
-        pdoc.static.html_out(dst, [one])
+        pdoc.static.html_out(dst, [one], markup)
         assert pdoc.static.would_overwrite(dst, [one])
         assert pdoc.static.would_overwrite(dst, [one, two])
-        pdoc.static.html_out(dst, [one, two])
+        pdoc.static.html_out(dst, [one, two], markup)
         assert pdoc.static.would_overwrite(dst, [one])
         assert pdoc.static.would_overwrite(dst, [one, two])