Merge pull request #184 from dhellmann/inline-directive

feature: domain and role

docs/source/customize.rst

@@ -1,7 +1,3 @@
-.. spelling::
-
-   wikis
-
 =======================
  Configuration Options
 =======================
@@ -102,7 +98,7 @@ returned by the tokenizer to be checked.
 ``spelling_ignore_wiki_words=True``
 
   Boolean controlling whether words that follow the CamelCase
-  conventions used for page names in wikis should be treated as
+  conventions used for page names in :spelling:word:`wikis` should be treated as
   spelled properly. Defaults to ``True``.
 
 ``spelling_ignore_acronyms=True``

docs/source/developers.rst

@@ -1,4 +1,4 @@
-.. spelling::
+.. spelling:word-list::
 
    sphinxcontrib
    reStructuredText

docs/source/history.rst

@@ -2,14 +2,25 @@
  Release History
 =================
 
-.. spelling::
+.. spelling:word-list::
 
    Homebrew
    libenchant
    macOS
    unmaintained
 
 
+Unreleased
+==========
+
+Features
+--------
+
+- Convert to use Sphinx domains. Add ``spelling:word-list``
+  directive. Have ``spelling`` directive report that it is deprecated.
+- Add ``spelling:word`` role for marking inline text as spelled
+  correctly.
+
 7.5.1
 =====
 

docs/source/index.rst

@@ -1,4 +1,4 @@
-.. spelling::
+.. spelling:word-list::
 
    sphinxcontrib
 

docs/source/install.rst

@@ -1,4 +1,4 @@
-.. spelling::
+.. spelling:word-list::
 
    sphinxcontrib
 

sphinxcontrib/spelling/__init__.py

@@ -7,23 +7,22 @@
 
 from sphinx.util import logging
 
-from .asset import SpellingCollector
-from .builder import SpellingBuilder
-from .directive import SpellingDirective
+from . import asset, builder, directive, domain
 
 logger = logging.getLogger(__name__)
 
 
 def setup(app):
     version = importlib_metadata.version('sphinxcontrib-spelling')
     logger.info('Initializing Spelling Checker %s', version)
-    app.add_builder(SpellingBuilder)
+    app.add_builder(builder.SpellingBuilder)
     # Register the 'spelling' directive for setting parameters within
     # a document
-    app.add_directive('spelling', SpellingDirective)
+    app.add_directive('spelling', directive.LegacySpellingDirective)
+    app.add_domain(domain.SpellingDomain)
     # Register an environment collector to merge data gathered by the
     # directive in parallel builds
-    app.add_env_collector(SpellingCollector)
+    app.add_env_collector(asset.SpellingCollector)
     # Report guesses about correct spelling
     app.add_config_value('spelling_show_suggestions', False, 'env')
     # Limit the number of suggestions output

sphinxcontrib/spelling/directive.py

@@ -12,6 +12,16 @@
 logger = logging.getLogger(__name__)
 
 
+def add_good_words_to_document(env, docname, good_words):
+    # Initialize the per-document good words list
+    if not hasattr(env, 'spelling_document_words'):
+        env.spelling_document_words = collections.defaultdict(list)
+    logger.info('Extending local dictionary for %s with %s',
+                env.docname, good_words)
+    print(env.docname, good_words)
+    env.spelling_document_words[env.docname].extend(good_words)
+
+
 class SpellingDirective(rst.Directive):
     """Custom directive for passing instructions to the spelling checker.
 
@@ -27,18 +37,20 @@ class SpellingDirective(rst.Directive):
     def run(self):
         env = self.state.document.settings.env
 
-        # Initialize the per-document good words list
-        if not hasattr(env, 'spelling_document_words'):
-            env.spelling_document_words = collections.defaultdict(list)
-
         good_words = []
         for entry in self.content:
             if not entry:
                 continue
             good_words.extend(entry.split())
         if good_words:
-            logger.debug('Extending local dictionary for %s with %s',
-                         env.docname, good_words)
-            env.spelling_document_words[env.docname].extend(good_words)
+            add_good_words_to_document(env, env.docname, good_words)
 
         return []
+
+
+class LegacySpellingDirective(SpellingDirective):
+
+    def run(self):
+        logger.info('direct use of the spelling directive is deprecated, '
+                    'replace ".. spelling::" with ".. spelling:word-list::"')
+        return super().run()

sphinxcontrib/spelling/domain.py

@@ -0,0 +1,30 @@
+from docutils import nodes
+from sphinx.domains import Domain
+
+from . import directive, role
+
+
+class SpellingDomain(Domain):
+
+    name = 'spelling'
+    label = 'Spelling Checker'
+    directives = {
+        'word-list': directive.SpellingDirective,
+    }
+    roles = {
+        'word': role.WordRole('spelling:word', nodes.Text),
+    }
+
+    def get_objects(self):
+        return []
+
+    def resolve_xref(self, env, fromdocname, builder, typ, target, node,
+                     contnode):
+        return None
+
+    def resolve_any_xref(self, env, fromdocname, builder, target, node,
+                         contnode):
+        return []
+
+    def merge_domaindata(self, docnames, otherdata):
+        pass

sphinxcontrib/spelling/role.py

@@ -0,0 +1,17 @@
+from docutils.parsers.rst import roles
+
+from . import directive
+
+
+class WordRole(roles.GenericRole):
+    """Let the user indicate that inline text is spelled correctly.
+    """
+
+    def __call__(self, role, rawtext, text, lineno, inliner,
+                 options={}, content=[]):
+        env = inliner.document.settings.env
+        docname = env.docname
+        good_words = text.split()
+        directive.add_good_words_to_document(env, docname, good_words)
+        return super().__call__(role, rawtext, text, lineno, inliner,
+                                options=options, content=content)

tests/test_builder.py

@@ -351,3 +351,87 @@ def test_captions(sphinx_project):
         'contents',
     )
     assert '(Teh)' in output_text
+
+
+def test_legacy_directive(sphinx_project):
+    srcdir, outdir = sphinx_project
+
+    add_file(srcdir, 'contents.rst', '''
+    The Module
+    ==========
+
+    .. spelling::
+
+       teh
+
+    teh is OK
+
+    ''')
+
+    stdout, stderr, output_text = get_sphinx_output(
+        srcdir,
+        outdir,
+        'contents',
+    )
+    assert output_text is None
+
+
+def test_domain_directive(sphinx_project):
+    srcdir, outdir = sphinx_project
+
+    add_file(srcdir, 'contents.rst', '''
+    The Module
+    ==========
+
+    .. spelling:word-list::
+
+       teh
+
+    teh is OK
+
+    ''')
+
+    stdout, stderr, output_text = get_sphinx_output(
+        srcdir,
+        outdir,
+        'contents',
+    )
+    assert output_text is None
+
+
+def test_domain_role(sphinx_project):
+    srcdir, outdir = sphinx_project
+
+    add_file(srcdir, 'contents.rst', '''
+    The Module
+    ==========
+
+    :spelling:word:`teh` is OK
+
+    ''')
+
+    stdout, stderr, output_text = get_sphinx_output(
+        srcdir,
+        outdir,
+        'contents',
+    )
+    assert output_text is None
+
+
+def test_domain_role_multiple_words(sphinx_project):
+    srcdir, outdir = sphinx_project
+
+    add_file(srcdir, 'contents.rst', '''
+    The Module
+    ==========
+
+    :spelling:word:`teh is KO`
+
+    ''')
+
+    stdout, stderr, output_text = get_sphinx_output(
+        srcdir,
+        outdir,
+        'contents',
+    )
+    assert output_text is None