Refactor to make sphinx a soft dependency

conftest.py

@@ -0,0 +1,15 @@
+# Configure test collection to skip doctests for modules that depend on sphinx
+# when sphinx is not available in the environment.
+
+try:
+    import sphinx
+
+    has_sphinx = True
+except ImportError:
+    has_sphinx = False
+
+
+collect_ignore = []
+
+if not has_sphinx:
+    collect_ignore += ["numpydoc/numpydoc.py", "numpydoc/docscrape_sphinx.py"]

numpydoc/__init__.py

@@ -5,8 +5,15 @@
 
 from ._version import __version__
 
+# NOTE: Determine whether sphinx is installed with an explicit import.
+# If so, define the setup function for registering the numpydoc extension;
+# otherwise skip this step.
+try:
+    import sphinx
 
-def setup(app, *args, **kwargs):
-    from .numpydoc import setup
+    def setup(app, *args, **kwargs):
+        from .numpydoc import setup
 
-    return setup(app, *args, **kwargs)
+        return setup(app, *args, **kwargs)
+except ModuleNotFoundError:
+    pass

numpydoc/_utils.py

@@ -0,0 +1,13 @@
+import re
+
+
+def _clean_text_signature(sig):
+    if sig is None:
+        return None
+    start_pattern = re.compile(r"^[^(]*\(")
+    start, end = start_pattern.search(sig).span()
+    start_sig = sig[start:end]
+    sig = sig[end:-1]
+    sig = re.sub(r"^\$(self|module|type)(,\s|$)", "", sig, count=1)
+    sig = re.sub(r"(^|(?<=,\s))/,\s\*", "*", sig, count=1)
+    return start_sig + sig + ")"

numpydoc/cli.py

@@ -6,7 +6,8 @@
 from pathlib import Path
 from typing import List
 
-from .docscrape_sphinx import get_doc_object
+from numpydoc.docscrape import get_doc_object
+
 from .hooks import utils, validate_docstrings
 from .validate import ERROR_MSGS, Validator, validate
 

numpydoc/docscrape.py

@@ -574,7 +574,7 @@ def dedent_lines(lines):
 
 
 class FunctionDoc(NumpyDocString):
-    def __init__(self, func, role="func", doc=None, config=None):
+    def __init__(self, func, role=None, doc=None, config=None):
         self._f = func
         self._role = role  # e.g. "func" or "meth"
 

numpydoc/numpydoc.py

@@ -34,6 +34,7 @@
 from sphinx.util import logging
 
 from . import __version__
+from ._utils import _clean_text_signature
 from .docscrape_sphinx import get_doc_object
 from .validate import get_validation_checks, validate
 from .xref import DEFAULT_LINKS
@@ -301,18 +302,6 @@ def mangle_signature(app: SphinxApp, what, name, obj, options, sig, retann):
         return sig, ""
 
 
-def _clean_text_signature(sig):
-    if sig is None:
-        return None
-    start_pattern = re.compile(r"^[^(]*\(")
-    start, end = start_pattern.search(sig).span()
-    start_sig = sig[start:end]
-    sig = sig[end:-1]
-    sig = re.sub(r"^\$(self|module|type)(,\s|$)", "", sig, count=1)
-    sig = re.sub(r"(^|(?<=,\s))/,\s\*", "*", sig, count=1)
-    return start_sig + sig + ")"
-
-
 def setup(app: SphinxApp, get_doc_object_=get_doc_object):
     if not hasattr(app, "add_config_value"):
         return None  # probably called by nose, better bail out