New plugin: pdoc

getnikola · Sep 24, 2018 · 4860a6a · 4860a6a
1 parent 53e9a25
commit 4860a6a
Show file tree

Hide file tree

Showing 4 changed files with 136 additions and 0 deletions.
diff --git a/v8/pdoc/README.md b/v8/pdoc/README.md
@@ -0,0 +1,28 @@
+Compiler plugin to Document Python modules using PDoc.
+
+This module allows you to create Nikola pages based on the documentation for a python module or identifier.
+
+Just create the page as usual:
+
+```
+nikola new_page -f pdoc
+```
+
+And as **content** in the page, put a module name, for example, this will create a page with the documentation for the csv module:
+
+```
+csv
+```
+
+You can also use a module and an identifier. To document the excel identifier in the csv module:
+
+```
+csv excel
+```
+
+This is still rather raw, the output doesn't look great, the JS interactions are broken, and CSS is lacking, but it's a start.
+
+[More information about PDoc](https://github.com/mitmproxy/pdoc)
+
+
+
diff --git a/v8/pdoc/pdoc.plugin b/v8/pdoc/pdoc.plugin
@@ -0,0 +1,13 @@
+[Core]
+name = pdoc
+module = pdoc
+
+[Documentation]
+author = Roberto Alsina
+version = 0.1
+website = https://pliugins.getnikola.com/
+description = Add module documentation as a page using pdoc
+
+[Nikola]
+PluginCategory = Compiler
+friendlyname = PDoc
diff --git a/v8/pdoc/pdoc.py b/v8/pdoc/pdoc.py
@@ -0,0 +1,94 @@
+# -*- coding: utf-8 -*-
+
+# Copyright © 2012-2018 Roberto Alsina and others.
+
+# Permission is hereby granted, free of charge, to any
+# person obtaining a copy of this software and associated
+# documentation files (the "Software"), to deal in the
+# Software without restriction, including without limitation
+# the rights to use, copy, modify, merge, publish,
+# distribute, sublicense, and/or sell copies of the
+# Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice
+# shall be included in all copies or substantial portions of
+# the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
+# PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+# OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+# OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+# OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+# SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+"""Page compiler plugin for Python Modules using PDoc."""
+
+
+import io
+import os
+import shlex
+import subprocess
+import tempfile
+
+
+from nikola import shortcodes as sc
+from nikola.plugin_categories import PageCompiler
+from nikola.utils import LocaleBorg, makedirs, map_metadata, write_metadata
+
+
+class CompilePdoc(PageCompiler):
+    """Compile docstrings into HTML."""
+
+    name = "pdoc"
+    friendly_name = "PDoc"
+    supports_metadata = True
+
+    def compile_string(self, data, source_path=None, is_two_file=True, post=None, lang=None):
+        """Compile docstrings into HTML strings, with shortcode support."""
+        if not is_two_file:
+            _, data = self.split_metadata(data, post, lang)
+        new_data, shortcodes = sc.extract_shortcodes(data)
+        # The way pdoc generates output is a bit inflexible
+        with tempfile.TemporaryDirectory() as tmpdir:
+            subprocess.check_call(['pdoc', '--html', '--html-dir', tmpdir] + shlex.split(data.strip()))
+            fname = os.listdir(tmpdir)[0]
+            with open(fname, 'r', encoding='utf8') as inf:
+                output = inf.read()
+        return self.site.apply_shortcodes_uuid(output, shortcodes, filename=source_path, extra_context={'post': post})
+
+    def compile(self, source, dest, is_two_file=True, post=None, lang=None):
+        """Compile the docstring into HTML and save as dest."""
+        makedirs(os.path.dirname(dest))
+        with io.open(dest, "w+", encoding="utf8") as out_file:
+            with io.open(source, "r", encoding="utf8") as in_file:
+                data = in_file.read()
+            data, shortcode_deps = self.compile_string(data, source, is_two_file, post, lang)
+            out_file.write(data)
+        if post is None:
+            if shortcode_deps:
+                self.logger.error(
+                    "Cannot save dependencies for post {0} (post unknown)",
+                    source)
+        else:
+            post._depfile[dest] += shortcode_deps
+        return True
+
+    def create_post(self, path, **kw):
+        """Create a new post."""
+        content = kw.pop('content', None)
+        onefile = kw.pop('onefile', False)
+        # is_page is not used by create_post as of now.
+        kw.pop('is_page', False)
+        metadata = {}
+        metadata.update(self.default_metadata)
+        metadata.update(kw)
+        makedirs(os.path.dirname(path))
+        if not content.endswith('\n'):
+            content += '\n'
+        with io.open(path, "w+", encoding="utf8") as fd:
+            if onefile:
+                fd.write(write_metadata(metadata, comment_wrap=True, site=self.site, compiler=self))
+            fd.write(content)
diff --git a/v8/pdoc/requirements.txt b/v8/pdoc/requirements.txt
@@ -0,0 +1 @@
+pdoc