Made dependencies of other languages optional (#171)

* Fixes #170

* Makes sphinxcontrib-golangdomain and
sphinxcontrib-dotnetdomain to be optional
packages
* Adds check that appropriate dependencies of
a specified api-type installed during the
extension initialisation
* Adds appropriate tests

autoapi/backends.py

@@ -25,3 +25,13 @@ default_backend_mapping = {
     "go": GoSphinxMapper,
     "javascript": JavaScriptSphinxMapper,
 }
+
+
+#: describes backend requirements in form
+#: {'backend name': (('1st package name in pypi', '1st package import name'), ...)}
+backend_requirements = {
+    "python": (),
+    "javascript": (),
+    "go": (("sphinxcontrib-golangdomain", "sphinxcontrib.golangdomain"),),
+    "dotnet": (("sphinxcontrib-dotnetdomain", "sphinxcontrib.dotnetdomain"),),
+}  # type: Dict[str, Sequence[Tuple[str, str]]]

autoapi/extension.py

@@ -7,6 +7,7 @@ This extension allows you to automagically generate API documentation from your
 import io
 import os
 import shutil
+import sys
 
 import sphinx
 from sphinx.util.console import darkgreen, bold
@@ -21,6 +22,7 @@ from .backends import (
     default_file_mapping,
     default_ignore_patterns,
     default_backend_mapping,
+    backend_requirements,
 )
 from .directives import AutoapiSummary, NestedParse
 from .settings import API_ROOT
@@ -40,6 +42,16 @@ def run_autoapi(app):
     """
     Load AutoAPI data from the filesystem.
     """
+    if app.config.autoapi_type not in default_backend_mapping:
+        raise ExtensionError(
+            "Invalid autoapi_type setting, "
+            "following values is allowed: {}".format(
+                ", ".join(
+                    '"{}"'.format(api_type)
+                    for api_type in sorted(default_backend_mapping)
+                )
+            )
+        )
 
     if not app.config.autoapi_dirs:
         raise ExtensionError("You must configure an autoapi_dirs setting")
@@ -67,6 +79,26 @@ def run_autoapi(app):
     )
     url_root = os.path.join("/", app.config.autoapi_root)
 
+    if not all(
+        import_name in sys.modules
+        for _, import_name in backend_requirements[app.config.autoapi_type]
+    ):
+        raise ExtensionError(
+            "AutoAPI of type `{type}` requires following "
+            "packages to be installed and included in extensions list: "
+            "{packages}".format(
+                type=app.config.autoapi_type,
+                packages=", ".join(
+                    '{import_name} (available as "{pkg_name}" on PyPI)'.format(
+                        pkg_name=pkg_name, import_name=import_name
+                    )
+                    for pkg_name, import_name in backend_requirements[
+                        app.config.autoapi_type
+                    ]
+                ),
+            )
+        )
+
     sphinx_mapper = default_backend_mapping[app.config.autoapi_type]
     sphinx_mapper_obj = sphinx_mapper(
         app, template_dir=app.config.autoapi_template_dir, url_root=url_root

setup.py

@@ -20,10 +20,12 @@ setup(
         'Jinja2',
         'PyYAML',
         'sphinx>=1.6',
-        'sphinxcontrib-golangdomain',
-        'sphinxcontrib-dotnetdomain',
         'unidecode',
     ],
+    extras_require={
+        'go': ['sphinxcontrib-golangdomain'],
+        'dotnet': ['sphinxcontrib-dotnetdomain']
+    },
     python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*',
     classifiers=[
         'Development Status :: 4 - Beta',

tests/test_integration.py

@@ -11,6 +11,7 @@ import pytest
 
 import sphinx
 from sphinx.application import Sphinx
+from sphinx.errors import ExtensionError
 
 
 @contextmanager
@@ -108,3 +109,54 @@ class TOCTreeTests(LanguageIntegrationTests):
         Test that the example_function gets added to the TOC Tree
         """
         self._run_test("toctreeexample", "_build/text/index.txt", "* example_function")
+
+
+class TestExtensionErrors:
+    @pytest.fixture(autouse=True)
+    def unload_go_and_dotned_libraries(self):
+        # unload dotnet and golang domain libraries, because they may be imported before
+        for mod_name in ("sphinxcontrib.dotnetdomain", "sphinxcontrib.golangdomain"):
+            try:
+                del sys.modules[mod_name]
+            except KeyError:
+                pass
+
+    @pytest.mark.parametrize(
+        "proj_name, override_conf, err_msg",
+        [
+            (
+                "toctreeexample",
+                {"autoapi_type": "INVALID VALUE"},
+                (
+                    "Invalid autoapi_type setting, following values is "
+                    'allowed: "dotnet", "go", "javascript", "python"'
+                ),
+            ),
+            (
+                "goexample",
+                {"autoapi_type": "go", "extensions": ["autoapi.extension"]},
+                (
+                    "AutoAPI of type `go` requires following "
+                    "packages to be installed and included in extensions list: "
+                    "sphinxcontrib.golangdomain (available as "
+                    '"sphinxcontrib-golangdomain" on PyPI)'
+                ),
+            ),
+            (
+                "dotnetexample",
+                {"autoapi_type": "dotnet", "extensions": ["autoapi.extension"]},
+                (
+                    "AutoAPI of type `dotnet` requires following "
+                    "packages to be installed and included in extensions list: "
+                    "sphinxcontrib.dotnetdomain (available as "
+                    '"sphinxcontrib-dotnetdomain" on PyPI)'
+                ),
+            ),
+        ],
+    )
+    def test_extension_setup_errors(self, proj_name, override_conf, err_msg):
+        with pytest.raises(ExtensionError) as err_info:
+            with sphinx_build(proj_name, override_conf):
+                pass
+
+        assert str(err_info.value) == err_msg

tox.ini

@@ -19,6 +19,8 @@ setenv =
 deps = -r{toxinidir}/requirements.txt
     pytest
     mock
+    sphinxcontrib-golangdomain
+    sphinxcontrib-dotnetdomain
     sphinx16: Sphinx<1.7
     sphinx17: Sphinx<1.8
     sphinx18: Sphinx<1.9