Get rid of inheritance

Introduce zope.interface

Author: hynek

doc2dash/__main__.py

@@ -11,6 +11,7 @@
 import click
 
 from . import __version__, parsers
+from .parsers.utils import patch_anchors
 
 
 log = logging.getLogger(__name__)
@@ -110,7 +111,7 @@ def main(source, force, name, quiet, verbose, destination, add_to_dash,
         )
         raise SystemExit(errno.EINVAL)
     docs, db_conn = prepare_docset(source, dest, name, index_page)
-    doc_parser = dt(docs)
+    doc_parser = dt(doc_path=docs)
     log.info(('Converting ' + click.style('{parser_name}', bold=True) +
               ' docs from "{src}" to "{dst}".')
              .format(parser_name=dt.name,
@@ -119,7 +120,7 @@ def main(source, force, name, quiet, verbose, destination, add_to_dash,
 
     with db_conn:
         log.info('Parsing documentation...')
-        toc = doc_parser.add_toc(show_progressbar=not quiet)
+        toc = patch_anchors(doc_parser, show_progressbar=not quiet)
         for entry in doc_parser.parse():
             db_conn.execute(
                 'INSERT INTO searchIndex VALUES (NULL, ?, ?, ?)',
@@ -139,7 +140,7 @@ def main(source, force, name, quiet, verbose, destination, add_to_dash,
         add_icon(icon_data, dest)
 
     if add_to_dash or add_to_global:
-        log.info('Adding to dash...')
+        log.info('Adding to Dash.app...')
         os.system('open -a dash "{}"'.format(dest))
 
 

doc2dash/parsers/__init__.py

@@ -5,8 +5,8 @@
 
 DOCTYPES = [
     intersphinx.InterSphinxParser,
-    sphinx.SphinxParser,
     pydoctor.PyDoctorParser,
+    sphinx.SphinxParser,
 ]
 
 

doc2dash/parsers/base.py

@@ -3,12 +3,18 @@
 import logging
 import os
 
+from characteristic import attributes
 from six import iteritems
 from sphinx.ext.intersphinx import read_inventory_v2
+from zope.interface import implementer
 
 from . import types
-from .base import _BaseParser, ParserEntry
-from .sphinx import find_and_patch_entry
+from .utils import (
+    APPLE_REF_TEMPLATE,
+    IParser,
+    ParserEntry,
+    has_file_with,
+)
 
 
 log = logging.getLogger(__name__)
@@ -36,24 +42,28 @@
 }
 
 
-class InterSphinxParser(_BaseParser):
+@implementer(IParser)
+@attributes(["doc_path"])
+class InterSphinxParser(object):
     """
     Parser for Sphinx-base documentation that generates an objects.inv file for
     the intersphinx extension.
     """
     name = "intersphinx"
 
-    DETECT_FILE = "objects.inv"
-    DETECT_PATTERN = b"# Sphinx inventory version 2"
+    @staticmethod
+    def detect(path):
+        return has_file_with(
+            path, "objects.inv", b"# Sphinx inventory version 2"
+        )
 
     def parse(self):
         """
-        Parse sphinx docs at self.docpath.
+        Parse sphinx docs at self.doc_path.
 
-        yield tuples of symbol name, type and path
+        yield `ParserEntry`s.
         """
-        log.info('Creating database...')
-        with open(os.path.join(self.docpath, "objects.inv"), "rb") as inv_f:
+        with open(os.path.join(self.doc_path, "objects.inv"), "rb") as inv_f:
             inv_f.readline()  # skip version line that is verified in detection
             for pe in _inv_to_entries(
                     read_inventory_v2(inv_f, "", os.path.join)
@@ -64,6 +74,23 @@ def find_and_patch_entry(self, soup, entry):  # pragma: nocover
         return find_and_patch_entry(soup, entry)
 
 
+def find_and_patch_entry(soup, entry):
+    """
+    Modify soup so Dash.app can generate TOCs on the fly.
+    """
+    link = soup.find('a', {'class': 'headerlink'}, href='#' + entry.anchor)
+    tag = soup.new_tag('a')
+    tag['name'] = APPLE_REF_TEMPLATE.format(entry.type, entry.name)
+    if link:
+        link.parent.insert(0, tag)
+        return True
+    elif entry.anchor.startswith('module-'):
+        soup.h1.parent.insert(0, tag)
+        return True
+    else:
+        return False
+
+
 def _inv_to_entries(inv):
     """
     Iterate over a dictionary as returned from Sphinx's object.inv parser and

doc2dash/parsers/intersphinx.py

@@ -4,36 +4,45 @@
 import os
 
 from bs4 import BeautifulSoup
+from characteristic import attributes
+from zope.interface import implementer
 
 from . import types
-from .base import _BaseParser, APPLE_REF_TEMPLATE, ParserEntry
+from .utils import APPLE_REF_TEMPLATE, ParserEntry, has_file_with, IParser
 
 
 log = logging.getLogger(__name__)
 
 
-class PyDoctorParser(_BaseParser):
+PYDOCTOR_HEADER = b'''\
+      This documentation was automatically generated by
+      <a href="http://codespeak.net/~mwh/pydoctor/">pydoctor</a>'''
+
+
+@implementer(IParser)
+@attributes(["doc_path"])
+class PyDoctorParser(object):
     """
     Parser for pydoctor-based documentation: mainly Twisted.
     """
     name = 'pydoctor'
 
-    DETECT_FILE = 'index.html'
-    DETECT_PATTERN = b'''\
-      This documentation was automatically generated by
-      <a href="http://codespeak.net/~mwh/pydoctor/">pydoctor</a>'''
+    @classmethod
+    def detect(self, path):
+        return has_file_with(
+            path, "index.html", PYDOCTOR_HEADER
+        )
 
     def parse(self):
         """
-        Parse pydoctor docs at *docpath*.
+        Parse pydoctor docs at *doc_path*.
 
-        yield ParserEntrys
+        yield `ParserEntry`s
         """
         soup = BeautifulSoup(
-            open(os.path.join(self.docpath, 'nameIndex.html')),
+            open(os.path.join(self.doc_path, 'nameIndex.html')),
             'lxml'
         )
-        log.info('Creating database...')
         for tag in soup.body.find_all('a'):
             path = tag.get('href')
             if path and not path.startswith('#'):