1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
.. .. spelling::
.. wikis
=======================
Configuration Options
=======================
These options can be set in ``conf.py`` along with the other Sphinx
configuration settings.
Input Options
=============
``spelling_lang='en_US'``
String specifying the language, as understood by PyEnchant and
enchant. Defaults to ``en_US`` for US English.
``spelling_word_list_filename='spelling_wordlist.txt'``
String specifying a file containing a list of words known to be
spelled correctly but that do not appear in the language dictionary
selected by ``spelling_lang``. The file should contain one word per
line. Refer to the `PyEnchant tutorial`_
for
details.
.. _PyEnchant tutorial: http://packages.python.org/pyenchant/tutorial.html
Output Options
==============
``spelling_show_suggestions=False``
Boolean controlling whether suggestions for misspelled words are
printed. Defaults to False.
Word Filters
============
Enable or disable the built-in filters to control which words are
returned by the tokenizer to be checked.
``spelling_ignore_pypi_package_names=False``
Boolean controlling whether words that look like package names from
PyPI are treated as spelled properly. When ``True``, the current
list of package names is downloaded at the start of the build and
used to extend the list of known words in the dictionary. Defaults
to ``False``.
``spelling_ignore_wiki_words=True``
Boolean controlling whether words that follow the CamelCase
conventions used for page names in wikis should be treated as
spelled properly. Defaults to ``True``.
``spelling_ignore_acronyms=True``
Boolean controlling treatment of words that appear in all capital
letters, or all capital letters followed by a lower case ``s``. When
``True``, acronyms are assumed to be spelled properly. Defaults to
``True``.
``spelling_ignore_python_builtins=True``
Boolean controlling whether names built in to Python should be
treated as spelled properly. Defaults to ``True``.
``spelling_ignore_importable_modules=True``
Boolean controlling whether words that are names of modules found on
``sys.path`` are treated as spelled properly. Defaults to ``True``.
``spelling_filters=[]``
List of filter classes to be added to the tokenizer that produces
words to be checked. The classes should be derived from
``enchant.tokenize.Filter``. Refer to the `PyEnchant tutorial`_
for examples.
Private Dictionaries
====================
There are two ways to provide a list of known good words. The
``spelling_word_list_filename`` option (described above) specifies the
name of a plain text file containing one word per line. All of the
words in the file are assumed to be spelled correctly and may appear
in any part of the document being processed.
The ``spelling`` directive can be used to create a list of words known
to be spelled correctly within a single file. For example, if a
document refers to a person or project by name, the name can be added
to the list of known words for just that document.
::
.. spelling::
Docutils
Goodger
.. _PyEnchant: http://www.rfk.id.au/software/pyenchant/
Custom Word Filters
===================
The PyEnchant tokenizer supports a "filtering" API for processing
words from the input. Filters can alter the stream of words by adding,
replacing, or dropping values.
New filters should be derived from ``enchant.tokenize.Filter`` and
implement either the ``_split()`` method (to add or replace words) or
``_skip()`` (to treat words as being spelled correctly). For example,
this :class:`AcronymFilter` skips words that are all uppercase letters
or all uppercase with a trailing lowercase "s".
::
class AcronymFilter(Filter):
"""If a word looks like an acronym (all upper case letters),
ignore it.
"""
def _skip(self, word):
return (word.isupper() # all caps
or
# pluralized acronym ("URLs")
(word[-1].lower() == 's'
and
word[:-1].isupper()
)
)
To be used in a document, the custom filter needs to be installed
somewhere that Sphinx can import it while processing the input
files. The Sphinx project's ``conf.py`` then needs two changes.
1. Import the filter class.
2. Add the filter class to the ``spelling_filters`` configuration
variable.
::
from mymodule import MyFilter
spelling_filters = [MyFilter]
.. seealso::
* `Creating a Spelling Checker for reStructuredText Documents
<http://www.doughellmann.com/articles/how-tos/sphinxcontrib-spelling/>`_
* `PyEnchant tutorial`_
|
