Repository: sphinx-contrib/spelling

Issue:
Allow a limit for spelling_show_suggestions
It would be nice if there were a word limit for spelling_show_suggestions - maybe to show the 5 most relevant suggestions or something like that. Sometimes there are 15+ suggestions, and it can be quite a lot to look through.

Alternatively (or in addition), it could be better to see the suggestions list at the end, after the context statement

Discussion:

Patch:
diff --git a/docs/source/customize.rst b/docs/source/customize.rst
index 20137cc..92b91bc 100644
--- a/docs/source/customize.rst
+++ b/docs/source/customize.rst
@@ -52,7 +52,13 @@ Output Options
 ``spelling_show_suggestions=False``
 
   Boolean controlling whether suggestions for misspelled words are
-  printed.  Defaults to False.
+  printed.  Defaults to ``False``.
+
+``spelling_suggestion_limit=0``
+
+  Integer number of suggestions to emit when
+  ``spelling_show_suggestions`` is ``True``. Defaults to ``0``,
+  meaning no limit. Any positive value truncates the suggestion limit.
 
 ``spelling_show_whole_line=True``
 
diff --git a/docs/source/history.rst b/docs/source/history.rst
index be51108..f32248c 100644
--- a/docs/source/history.rst
+++ b/docs/source/history.rst
@@ -9,6 +9,17 @@
    macOS
    unmaintained
 
+Next
+====
+
+Features
+--------
+
+- `#151 <https://github.com/sphinx-contrib/spelling/issues/151>`__
+  Added configuration option to limit the number of suggestions
+  output. See :doc:`/customize` for more details. Idea contributed by
+  Trevor Gross.
+
 7.4.1
 =====
 
diff --git a/sphinxcontrib/spelling/__init__.py b/sphinxcontrib/spelling/__init__.py
index 02b9362..8bf763a 100644
--- a/sphinxcontrib/spelling/__init__.py
+++ b/sphinxcontrib/spelling/__init__.py
@@ -26,6 +26,8 @@ def setup(app):
     app.add_env_collector(SpellingCollector)
     # Report guesses about correct spelling
     app.add_config_value('spelling_show_suggestions', False, 'env')
+    # Limit the number of suggestions output
+    app.add_config_value('spelling_suggestion_limit', 0, 'env')
     # Report the whole line that has the error
     app.add_config_value('spelling_show_whole_line', True, 'env')
     # Emit misspelling as a sphinx warning instead of info message
diff --git a/sphinxcontrib/spelling/builder.py b/sphinxcontrib/spelling/builder.py
index 21178ee..169730c 100644
--- a/sphinxcontrib/spelling/builder.py
+++ b/sphinxcontrib/spelling/builder.py
@@ -148,10 +148,23 @@ class SpellingBuilder(Builder):
     def get_target_uri(self, docname, typ=None):
         return ''
 
-    def format_suggestions(self, suggestions):
+    def get_suggestions_to_show(self, suggestions):
         if not self.config.spelling_show_suggestions or not suggestions:
+            return []
+        to_show = suggestions
+        try:
+            n_to_show = int(self.config.spelling_suggestion_limit)
+        except ValueError:
+            n_to_show = 0
+        if n_to_show > 0:
+            to_show = suggestions[:n_to_show]
+        return to_show
+
+    def format_suggestions(self, suggestions):
+        to_show = self.get_suggestions_to_show(suggestions)
+        if not to_show:
             return ''
-        return '[' + ', '.join('"%s"' % s for s in suggestions) + ']'
+        return '[' + ', '.join('"%s"' % s for s in to_show) + ']'
 
     TEXT_NODES = {
         'block_quote',


Test patch:
diff --git a/tests/test_builder.py b/tests/test_builder.py
index 6ae85e2..0c1ce10 100644
--- a/tests/test_builder.py
+++ b/tests/test_builder.py
@@ -50,7 +50,7 @@ def add_file(thedir, filename, content):
         f.write(textwrap.dedent(content))
 
 
-def get_sphinx_output(srcdir, outdir, docname):
+def get_sphinx_app(srcdir, outdir, docname):
     stdout = io.StringIO()
     stderr = io.StringIO()
     app = Sphinx(
@@ -58,6 +58,11 @@ def get_sphinx_output(srcdir, outdir, docname):
         status=stdout, warning=stderr,
         freshenv=True,
     )
+    return (stdout, stderr, app)
+
+
+def get_sphinx_output(srcdir, outdir, docname):
+    stdout, stderr, app = get_sphinx_app(srcdir, outdir, docname)
     app.build()
     path = os.path.join(outdir, f'{docname}.spelling')
     try:
@@ -216,3 +221,39 @@ def test_docstrings(sphinx_project):
         ' (vaule)'
     )
     assert expected in output_text
+
+
+def test_get_suggestions_to_show_all(sphinx_project):
+    srcdir, outdir = sphinx_project
+    add_file(srcdir, 'conf.py', '''
+    extensions = ['sphinxcontrib.spelling']
+    spelling_show_suggestions = True
+    spelling_suggestion_limit = 0
+    ''')
+    stdout, stderr, app = get_sphinx_app(srcdir, outdir, 'contents')
+    results = app.builder.get_suggestions_to_show(['a', 'b', 'c'])
+    assert len(results) == 3
+
+
+def test_get_suggestions_to_show_limit(sphinx_project):
+    srcdir, outdir = sphinx_project
+    add_file(srcdir, 'conf.py', '''
+    extensions = ['sphinxcontrib.spelling']
+    spelling_show_suggestions = True
+    spelling_suggestion_limit = 1
+    ''')
+    stdout, stderr, app = get_sphinx_app(srcdir, outdir, 'contents')
+    results = app.builder.get_suggestions_to_show(['a', 'b', 'c'])
+    assert len(results) == 1
+
+
+def test_get_suggestions_to_show_disabled(sphinx_project):
+    srcdir, outdir = sphinx_project
+    add_file(srcdir, 'conf.py', '''
+    extensions = ['sphinxcontrib.spelling']
+    spelling_show_suggestions = False
+    spelling_suggestion_limit = 0
+    ''')
+    stdout, stderr, app = get_sphinx_app(srcdir, outdir, 'contents')
+    results = app.builder.get_suggestions_to_show(['a', 'b', 'c'])
+    assert len(results) == 0