Gracefully handle no objects being rendered

Closes #448

Author: AWhetter

autoapi/_mapper.py

@@ -359,6 +359,16 @@ def _output_top_rst(self):
         # Render Top Index
         top_level_index = os.path.join(self.dir_root, "index.rst")
         pages = [obj for obj in self.objects_to_render.values() if obj.display]
+        if not pages:
+            msg = (
+                "No modules were rendered. "
+                "Do you need to set autoapi_options to render additional objects?"
+            )
+            LOGGER.warning(
+                msg, type="autoapi", subtype="nothing_rendered"
+            )
+            return
+
         with open(top_level_index, "wb") as top_level_file:
             content = self.jinja_env.get_template("index.rst")
             top_level_file.write(content.render(pages=pages).encode("utf-8"))

autoapi/extension.py

@@ -124,6 +124,9 @@ def build_finished(app, exception):
         normalized_root = os.path.normpath(
             os.path.join(app.srcdir, app.config.autoapi_root)
         )
+        if not os.path.exists(normalized_root):
+            return
+
         if app.verbosity > 1:
             LOGGER.info(
                 colorize("bold", "[AutoAPI] ")

docs/changes/448.bugfix

@@ -0,0 +1 @@
+Gracefully handle no objects being rendered

docs/reference/config.rst

@@ -273,13 +273,19 @@ Suppressing Warnings
 
    If narrower suppression is wanted, the available subtypes for AutoAPI are:
 
-     * python_import_resolution
-       Used if resolving references to objects in an imported module failed. Potential reasons
-       include cyclical imports and missing (parent) modules.
-     * not_readable
-       Emitted if processing (opening, parsing, ...) an input file failed.
-     * toc_reference
-       Used if a reference to an entry in a table of content cannot be resolved.
+   * ``python_import_resolution``:
+     Emitted if resolving references to objects in an imported module failed.
+     Potential reasons include cyclical imports and missing (parent) modules.
+   * ``not_readable``:
+     Emitted if processing (opening, parsing, ...) an input file failed.
+   * ``toc_reference``:
+     Emitted if a reference to an entry in a table of content cannot be resolved.
+   * ``nothing_rendered``:
+     Emitted if nothing was found to be documented.
+     Potential reasons include no files being found in :confval:`autoapi_dirs`
+     that match :confval:`autoapi_file_patterns`,
+     or all discovered modules and objects being excluded from rendering due to
+     :confval:`autoapi_options` or :ref:`other rendering exclusions <customise-documented-api>`.
 
    So if all AutoAPI warnings concerning unreadable sources and failing Python imports should be
    filtered, but all other warnings should not, the option would be

tests/python/pynorender/conf.py

@@ -0,0 +1,22 @@
+templates_path = ["_templates"]
+source_suffix = ".rst"
+master_doc = "index"
+project = "pyexample"
+copyright = "2015, readthedocs"
+author = "readthedocs"
+version = "0.1"
+release = "0.1"
+language = "en"
+exclude_patterns = ["_build"]
+pygments_style = "sphinx"
+todo_include_todos = False
+html_theme = "alabaster"
+htmlhelp_basename = "pyexampledoc"
+extensions = ["sphinx.ext.autodoc", "autoapi.extension"]
+autoapi_dirs = ["example"]
+autoapi_python_class_content = "both"
+autoapi_options = [
+    "members",
+    "imported-members",
+    "inherited-members",
+]

tests/python/pynorender/example/_example.py

@@ -0,0 +1,7 @@
+def func() -> int:
+    """Returns five."""
+    return 5
+
+
+class Foo:
+    """This is a class."""

tests/python/pynorender/index.rst

@@ -0,0 +1,25 @@
+.. pyexample documentation master file, created by
+   sphinx-quickstart on Fri May 29 13:34:37 2015.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Welcome to pyexample's documentation!
+=====================================
+
+.. toctree::
+
+   autoapi/index
+
+Contents:
+
+.. toctree::
+   :maxdepth: 2
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

tests/python/test_pyintegration.py

@@ -1195,3 +1195,10 @@ def test_line_number_order(self, parse):
         method_sphinx_docs = example_file.find(id="example.Foo.method_sphinx_docs")
 
         assert method_tricky.sourceline < method_sphinx_docs.sourceline
+
+
+def test_nothing_to_render_raises_warning(builder):
+    with pytest.raises(sphinx.errors.SphinxWarning) as exc_info:
+        builder("pynorender", warningiserror=True)
+
+    assert "No modules were rendered" in str(exc_info.value)

tox.ini

@@ -19,6 +19,7 @@ python =
     3.13: py313
 
 [testenv]
+usedevelop = True
 deps =
     beautifulsoup4
     pytest