Add Sphinx spell check extension for docs

[ceh]

There's been a number of misspelled words in the documentation. This PR adds the ability to spell check the documentation via a make target.

Spell checking is implemented by adding a Sphinx spell check extension: http://sphinxcontrib-spelling.readthedocs.io/en/latest/

We use a dictionary file which contains words that are known to be spelled correctly, such as "mypy" and "Dataclasses".

Sample output:

$ make spellcheck
sphinx-build -b spelling -d build/doctrees   source build/spellcheck
Running Sphinx v1.7.5
Initializing Spelling Checker
loading pickled environment... done
Ignoring wiki words
Ignoring acronyms
Ignoring Python builtins
Ignoring importable module names
Looking for custom word list in /Users/ceh/src/python/mypy/docs/source/../dictionary.txt
building [mo]: targets for 0 po files that are out of date
building [spelling]: all documents
updating environment: [config changed] 29 added, 0 changed, 0 removed
reading sources... [100%] type_inference_and_annotations                                                                                                                           
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
installed_packages.rst:101:interpeter:["interpreter", "inter peter", "interpersonal", "interpenetrates", "interpreted", "interpretor"]                                             
more_types.rst:476:discrepency:["discrepancy", "discrepant", "discreteness", "discretionary", "discreetness"]                                                                      
writing output... [100%] type_inference_and_annotations                                                                                                                            
Spelling checker messages written to /Users/ceh/src/python/mypy/docs/build/spellcheck/output.txt
WARNING: Found 2 misspelled words
build succeeded, 1 warnings.

Spell check complete; look for any errors in the above output, or in build/spellcheck/output.txt.

The two misspelled words reported in the output are fixed in #5355

What do you think?

[ceh]

This is for ”await-ing” in

mypy/docs/source/more_types.rst

Line 576 in f5058bc

expect to get back when ``await``-ing the coroutine.

Which is a bit weird, and showcases the downside that the dictionary file would be need to be continuously maintained and updated.

[gvanrossum]

FWIW I don’t believe in batch spell checking. IMO it’s up to the text editor. But it’s Jukka’s docs so maybe he likes it?

[emmatyping]

If we do go ahead with this, it would be a good idea to add it to CI, so that we are all using it consistently.

[gvanrossum]

add it to CI

Yes, that would be the way to go, but I worry that we'd end up constantly updating the dictionary to teach it about words like unparameterized or unannotated...

[emmatyping]

I worry that we'd end up constantly updating the dictionary to teach it about words like unparameterized or unannotated...

I'm not particularly worried about that actually. 2000 or so words make up about 80% of all words used in a day. I expect for a technical document that is likely a lower percentage, but I don't think that much new vocabulary will be introduced. Of course, we can always try this, and if we find it annoying, rip it out.

[ceh]

Any final thoughts on the general idea, or should we just close this PR for now given the low traction?

[emmatyping]

Any final thoughts on the general idea, or should we just close this PR for now given the low traction?

I think we are waiting on @JukkaL to give an opinion. I don't see a problem with leaving this open for a while, unless you would like to withdraw this PR, in which case it is of course your prerogative to close it if you wish.

[JukkaL]

This seems like a reasonable idea to me -- we've had a lot of spelling mistakes, and catching them all without some automation is hard. If this turns out to be too noisy, we can turn this off. I'll play around with this a bit before merging (this might have to wait for a few weeks, since I'm going to be on vacation).