Debian Codegraph @

sphinxcontrib/spelling/builder.py

raw
1 #
2 # Copyright (c) 2010 Doug Hellmann. All rights reserved.
3 #
4 """Spelling checker extension for Sphinx.
5 """
6
7 import collections
8 import importlib
9 import os
10 import tempfile
11
12 import docutils.nodes
13 import docutils.utils
14 from sphinx.builders import Builder
15 from sphinx.util import logging, osutil
16 from sphinx.util.console import red
17 from sphinx.util.matching import Matcher
18 from sphinx.util.osutil import ensuredir
19
20 try:
21 from enchant.tokenize import EmailFilter, WikiWordFilter
22 except ImportError as imp_exc:
23 enchant_import_error = imp_exc
24 else:
25 enchant_import_error = None
26
27 from . import checker, filters
28
29 logger = logging.getLogger(__name__)
30
31 # TODO - Words with multiple uppercase letters treated as classes and ignored
32
33
34 class SpellingBuilder(Builder):
35 """
36 Spell checks a document
37 """
38 name = 'spelling'
39
40 def init(self):
41 if enchant_import_error is not None:
42 raise RuntimeError(
43 'Cannot initialize spelling builder '
44 'without PyEnchant installed') from enchant_import_error
45 self.misspelling_count = 0
46
47 self.env.settings["smart_quotes"] = False
48 # Initialize the per-document filters
49 if not hasattr(self.env, 'spelling_document_words'):
50 self.env.spelling_document_words = collections.defaultdict(list)
51
52 # Initialize the global filters
53 f = [
54 filters.ContractionFilter,
55 EmailFilter,
56 ]
57 if self.config.spelling_ignore_wiki_words:
58 logger.info('Ignoring wiki words')
59 f.append(WikiWordFilter)
60 if self.config.spelling_ignore_acronyms:
61 logger.info('Ignoring acronyms')
62 f.append(filters.AcronymFilter)
63 if self.config.spelling_ignore_pypi_package_names:
64 logger.info('Adding package names from PyPI to local dictionary…')
65 f.append(filters.PyPIFilterFactory())
66 if self.config.spelling_ignore_python_builtins:
67 logger.info('Ignoring Python builtins')
68 f.append(filters.PythonBuiltinsFilter)
69 if self.config.spelling_ignore_importable_modules:
70 logger.info('Ignoring importable module names')
71 f.append(filters.ImportableModuleFilter)
72 if self.config.spelling_ignore_contributor_names:
73 logger.info('Ignoring contributor names')
74 f.append(filters.ContributorFilter)
75 f.extend(self._load_filter_classes(self.config.spelling_filters))
76
77 if not os.path.isdir(self.outdir):
78 os.mkdir(self.outdir)
79
80 word_list = self.get_wordlist_filename()
81 logger.info('Looking for custom word list in %s', word_list)
82
83 self.checker = checker.SpellingChecker(
84 lang=self.config.spelling_lang,
85 tokenizer_lang=self.config.tokenizer_lang,
86 suggest=self.config.spelling_show_suggestions,
87 word_list_filename=word_list,
88 filters=f,
89 context_line=self.config.spelling_show_whole_line,
90 )
91
92 def _load_filter_classes(self, filters):
93 # Filters may be expressed in the configuration file using
94 # names, so look through them and import the referenced class
95 # and use that in the checker.
96 for filter_ in filters:
97 if not isinstance(filter_, str):
98 yield filter_
99 continue
100 module_name, _, class_name = filter_.rpartition('.')
101 mod = importlib.import_module(module_name)
102 yield getattr(mod, class_name)
103
104 def get_configured_wordlist_filenames(self):
105 "Returns the configured wordlist filenames."
106 word_list = self.config.spelling_word_list_filename
107 if word_list is None:
108 word_list = ['spelling_wordlist.txt']
109
110 if isinstance(word_list, str):
111 # Wordlist is a string. Split on comma in case it came
112 # from the command line, via -D, and has multiple values.
113 word_list = word_list.split(',')
114
115 return [
116 os.path.join(self.srcdir, p)
117 for p in word_list
118 ]
119
120 def get_wordlist_filename(self):
121 "Returns the filename of the wordlist to use when checking content."
122 filenames = self.get_configured_wordlist_filenames()
123 if len(filenames) == 1:
124 return filenames[0]
125 # In case the user has multiple word lists, we combine them
126 # into one large list that we pass on to the checker.
127 return self._build_combined_wordlist()
128
129 def _build_combined_wordlist(self):
130 # If we have a list, the combined list is the first list plus all words
131 # from the other lists. Otherwise, word_list is assumed to just be a
132 # string.
133 temp_dir = tempfile.mkdtemp()
134 combined_word_list = os.path.join(temp_dir,
135 'spelling_wordlist.txt')
136
137 with open(combined_word_list, 'w', encoding='UTF-8') as outfile:
138 for word_file in self.get_configured_wordlist_filenames():
139 # Paths are relative
140 long_word_file = os.path.join(self.srcdir, word_file)
141 logger.info('Adding contents of %s to custom word list',
142 long_word_file)
143 with open(long_word_file, encoding='UTF-8') as infile:
144 infile_contents = infile.readlines()
145 outfile.writelines(infile_contents)
146
147 # Check for newline, and add one if not present
148 if infile_contents and not infile_contents[-1].endswith('\n'):
149 outfile.write('\n')
150
151 return combined_word_list
152
153 def get_outdated_docs(self):
154 return 'all documents'
155
156 def prepare_writing(self, docnames):
157 return
158
159 def get_target_uri(self, docname, typ=None):
160 return ''
161
162 def get_suggestions_to_show(self, suggestions):
163 if not self.config.spelling_show_suggestions or not suggestions:
164 return []
165 to_show = suggestions
166 try:
167 n_to_show = int(self.config.spelling_suggestion_limit)
168 except ValueError:
169 n_to_show = 0
170 if n_to_show > 0:
171 to_show = suggestions[:n_to_show]
172 return to_show
173
174 def format_suggestions(self, suggestions):
175 to_show = self.get_suggestions_to_show(suggestions)
176 if not to_show:
177 return ''
178 return '[' + ', '.join('"%s"' % s for s in to_show) + ']'
179
180 TEXT_NODES = {
181 'block_quote',
182 'caption',
183 'paragraph',
184 'list_item',
185 'term',
186 'definition_list_item',
187 'title',
188 }
189
190 def write_doc(self, docname, doctree):
191 lines = list(self._find_misspellings(docname, doctree))
192 self.misspelling_count += len(lines)
193 if lines:
194 output_filename = os.path.join(self.outdir, f'{docname}.spelling')
195 logger.info('Writing %s', output_filename)
196 ensuredir(os.path.dirname(output_filename))
197 with open(output_filename, 'w', encoding='UTF-8') as output:
198 output.writelines(lines)
199
200 def _find_misspellings(self, docname, doctree):
201
202 excluded = Matcher(self.config.spelling_exclude_patterns)
203 if excluded(self.env.doc2path(docname, None)):
204 return
205 # Build the document-specific word filter based on any good
206 # words listed in spelling directives. If we have no such
207 # words, we want to push an empty list of filters so that we
208 # can always safely pop the filter stack when we are done with
209 # this document.
210 doc_filters = []
211 good_words = self.env.spelling_document_words.get(docname)
212 if good_words:
213 logger.debug('Extending local dictionary for %s', docname)
214 doc_filters.append(filters.IgnoreWordsFilterFactory(good_words))
215 self.checker.push_filters(doc_filters)
216
217 for node in doctree.traverse(docutils.nodes.Text):
218 if (node.tagname == '#text' and
219 node.parent and
220 node.parent.tagname in self.TEXT_NODES and
221 not hasattr(node, "spellingIgnore")):
222
223 # Get the location of the text being checked so we can
224 # report it in the output file. Nodes from text that
225 # comes in via an 'include' directive does not include
226 # the full path, so convert all to relative path
227 # for consistency.
228 source, node_lineno = docutils.utils.get_source_line(node)
229 source = osutil.relpath(source)
230
231 # Check the text of the node.
232 misspellings = self.checker.check(node.astext())
233 for (
234 word,
235 suggestions,
236 context_line,
237 line_offset
238 ) in misspellings:
239
240 # Avoid TypeError on nodes lacking a line number
241 # This happens for some node originating from docstrings
242 lineno = node_lineno
243 if lineno is not None:
244 lineno += line_offset
245
246 msg_parts = [
247 f'{source}:{lineno}: ',
248 'Spell check',
249 red(word),
250 ]
251 if self.format_suggestions(suggestions) != '':
252 msg_parts.append(self.format_suggestions(suggestions))
253 msg_parts.append(context_line)
254 msg = ': '.join(msg_parts) + '.'
255 if self.config.spelling_warning:
256 logger.warning(msg)
257 elif self.config.spelling_verbose:
258 logger.info(msg)
259 yield "%s:%s: (%s) %s %s\n" % (
260 source, lineno, word,
261 self.format_suggestions(suggestions),
262 context_line,
263 )
264
265 self.checker.pop_filters()
266 return
267
268 def finish(self):
269 if self.misspelling_count:
270 logger.warning('Found %d misspelled words',
271 self.misspelling_count)