fix: Handle unavailable docstring parsers

mkdocstrings · Feb 16, 2021 · bf04764 · bf04764
1 parent de0424a
commit bf04764
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 9 deletions.
diff --git a/src/pytkdocs/parsers/docstrings/__init__.py b/src/pytkdocs/parsers/docstrings/__init__.py
@@ -2,11 +2,18 @@
 
 from typing import Dict, Type
 
-from pytkdocs.parsers.docstrings.base import Parser
+from pytkdocs.parsers.docstrings.base import Parser, UnavailableParser
 from pytkdocs.parsers.docstrings.google import Google
-from pytkdocs.parsers.docstrings.numpy import Numpy
 from pytkdocs.parsers.docstrings.restructured_text import RestructuredText
 
+try:
+    from pytkdocs.parsers.docstrings.numpy import Numpy
+except ImportError:
+    Numpy = UnavailableParser(  # type: ignore
+        "pytkdocs must be installed with 'numpy-style' extra to parse Numpy docstrings"
+    )
+
+
 PARSERS: Dict[str, Type[Parser]] = {
     "google": Google,
     "restructured-text": RestructuredText,

diff --git a/src/pytkdocs/parsers/docstrings/base.py b/src/pytkdocs/parsers/docstrings/base.py
@@ -182,3 +182,17 @@ def parse_sections(self, docstring: str) -> List[Section]:
             A list of [`Section`][pytkdocs.parsers.docstrings.base.Section]s.
         """
         raise NotImplementedError
+
+
+class UnavailableParser:
+    def __init__(self, message):
+        self.message = message
+
+    def parse(self, docstring: str, context: Optional[dict] = None) -> Tuple[List[Section], List[str]]:
+        message = self.message
+        if "obj" in context:
+            message = f"{context['obj'].path}: {message}"
+        return [], [message]
+
+    def __call__(self, *args, **kwargs):
+        return self
diff --git a/src/pytkdocs/parsers/docstrings/numpy.py b/src/pytkdocs/parsers/docstrings/numpy.py
@@ -2,8 +2,8 @@
 import re
 from typing import List, Optional
 
-import docstring_parser
 from docstring_parser import parse
+from docstring_parser.common import Docstring, DocstringMeta
 
 from pytkdocs.parsers.docstrings.base import AnnotatedObject, Attribute, Parameter, Parser, Section, empty
 
@@ -49,7 +49,7 @@ def parse_sections(self, docstring: str) -> List[Section]:  # noqa: D102
     def read_parameters_section(
         self,
         docstring: str,
-        docstring_obj: docstring_parser.common.Docstring,
+        docstring_obj: Docstring,
     ) -> Optional[Section]:
         """
         Parse a "parameters" section.
@@ -99,7 +99,7 @@ def read_parameters_section(
     def read_attributes_section(
         self,
         docstring: str,
-        docstring_obj: docstring_parser.common.Docstring,
+        docstring_obj: Docstring,
     ) -> Optional[Section]:
         """
         Parse an "attributes" section.
@@ -131,7 +131,7 @@ def read_attributes_section(
     def read_exceptions_section(
         self,
         docstring: str,
-        docstring_obj: docstring_parser.common.Docstring,
+        docstring_obj: Docstring,
     ) -> Optional[Section]:
         """
         Parse an "exceptions" section.
@@ -156,7 +156,7 @@ def read_exceptions_section(
 
     def read_return_section(
         self,
-        docstring_obj: docstring_parser.common.Docstring,
+        docstring_obj: Docstring,
     ) -> Optional[Section]:
         """
         Parse a "returns" section.
@@ -191,7 +191,7 @@ def read_return_section(
     def read_examples_section(
         self,
         docstring: str,
-        docstring_obj: docstring_parser.common.Docstring,
+        docstring_obj: Docstring,
     ) -> Optional[Section]:
         """
         Parse an "examples" section.
@@ -206,7 +206,7 @@ def read_examples_section(
             (
                 meta.description
                 for meta in docstring_obj.meta
-                if isinstance(meta, docstring_parser.common.DocstringMeta) and meta.args[0] == "examples"
+                if isinstance(meta, DocstringMeta) and meta.args[0] == "examples"
             ),
             "",
         )