Add sphinx spellcheck addon (#4209)

Co-Authored-By: Frost Ming <[email protected]> Co-Authored-By: Sumana Harihareswara <[email protected]>
pypa · Apr 29, 2020 · 2f460a9 · 2f460a9
1 parent f553565
commit 2f460a9
Show file tree

Hide file tree

Showing 16 changed files with 234 additions and 61 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
diff --git a/Pipfile b/Pipfile
@@ -8,6 +8,7 @@ jedi = "*"
 isort = "*"
 rope = "*"
 passa = {git = "https://github.com/sarugaku/passa.git"}
+sphinxcontrib-spelling = "<4.3.0"
 
 [packages]
 

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/RELEASING.md b/RELEASING.md
@@ -105,6 +105,20 @@ $ export PIPENV_PYTHON=2.7
 $ pipenv install --dev && pytest -ra tests
 ```
 
+## Check Spelling in Documentation
+
+Pipenv now leverages `sphinxcontrib.spelling` to help ensure documentation does not contain typographical mistakes. To validate documentation, please make sure to rebuild and rectify any documentation issues before pushing the new release:
+
+```console
+$ pipenv shell
+$ cd docs
+$ make clean && make html
+$ make spelling
+```
+
+Validate the results, adding any new exceptions to `docs/spelling_wordlist.txt`.
+
+
 ## Releasing
 
 1. Set a version: `pipenv run inv release.bump-version --trunc-month --pre --tag=a` - this will truncate the current month, creating an alpha pre-release, e.g. `2020.4.1a1`

diff --git a/docs/advanced.rst b/docs/advanced.rst
@@ -41,7 +41,7 @@ Very fancy.
 ☤ Using a PyPI Mirror
 ----------------------------
 
-If you'd like to override the default PyPI index urls with the url for a PyPI mirror, you can use the following::
+If you would like to override the default PyPI index URLs with the URL for a PyPI mirror, you can use the following::
 
     $ pipenv install --pypi-mirror <mirror_url>
 
@@ -467,7 +467,7 @@ In addition, you can also have Pipenv stick the virtualenv in ``project/.venv``
 
 Pipenv is being used in projects like `Requests`_ for declaring development dependencies and running the test suite.
 
-We've currently tested deployments with both `Travis-CI`_ and `tox`_ with success.
+We have currently tested deployments with both `Travis-CI`_ and `tox`_ with success.
 
 Travis CI
 /////////
@@ -549,11 +549,11 @@ A 3rd party plugin, `tox-pipenv`_ is also available to use Pipenv natively with
 ☤ Shell Completion
 ------------------
 
-To enable completion in fish, add this to your config::
+To enable completion in fish, add this to your configuration::
 
     eval (pipenv --completion)
 
-Alternatively, with bash or zsh, add this to your config::
+Alternatively, with bash or zsh, add this to your configuration::
 
     eval "$(pipenv --completion)"
 
@@ -587,9 +587,9 @@ at all, use the `PIP_IGNORE_INSTALLED` setting::
 
 There is a subtle but very important distinction to be made between **applications** and **libraries**. This is a very common source of confusion in the Python community.
 
-Libraries provide reusable functionality to other libraries and applications (let's use the umbrella term **projects** here). They are required to work alongside other libraries, all with their own set of subdependencies. They define **abstract dependencies**. To avoid version conflicts in subdependencies of different libraries within a project, libraries should never ever pin dependency versions. Although they may specify lower or (less frequently) upper bounds, if they rely on some specific feature/fix/bug. Library dependencies are specified via ``install_requires`` in ``setup.py``.
+Libraries provide reusable functionality to other libraries and applications (let's use the umbrella term **projects** here). They are required to work alongside other libraries, all with their own set of sub-dependencies. They define **abstract dependencies**. To avoid version conflicts in sub-dependencies of different libraries within a project, libraries should never ever pin dependency versions. Although they may specify lower or (less frequently) upper bounds, if they rely on some specific feature/fix/bug. Library dependencies are specified via ``install_requires`` in ``setup.py``.
 
-Libraries are ultimately meant to be used in some **application**. Applications are different in that they usually are not depended on by other projects. They are meant to be deployed into some specific environment and only then should the exact versions of all their dependencies and subdependencies be made concrete. To make this process easier is currently the main goal of Pipenv.
+Libraries are ultimately meant to be used in some **application**. Applications are different in that they usually are not depended on by other projects. They are meant to be deployed into some specific environment and only then should the exact versions of all their dependencies and sub-dependencies be made concrete. To make this process easier is currently the main goal of Pipenv.
 
 To summarize:
 

diff --git a/docs/conf.py b/docs/conf.py
@@ -18,7 +18,6 @@
 #
 import os
 
-
 # Path hackery to get current version number.
 here = os.path.abspath(os.path.dirname(__file__))
 
@@ -41,6 +40,7 @@
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
     'sphinx_click.ext',
+    'sphinxcontrib.spelling',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -87,6 +87,8 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+spelling_word_list_filename = "spelling_wordlist.txt"
+spelling_show_suggestions = True
 
 # -- Options for HTML output ----------------------------------------------
 

diff --git a/docs/dev/contributing.rst b/docs/dev/contributing.rst
@@ -118,10 +118,10 @@ To get your development environment setup, run:
   pipenv install --dev
 
 
-This will install the repo version of Pipenv and then install the development
+This will install the repository version of Pipenv and then install the development
 dependencies. Once that has completed, you can start developing.
 
-The repo version of Pipenv must be installed over other global versions to
+The repository version of Pipenv must be installed over other global versions to
 resolve conflicts with the ``pipenv`` folder being implicitly added to ``sys.path``.
 See `pypa/pipenv#2557`_ for more details.
 
@@ -152,7 +152,7 @@ tests, the standard pytest filters are available, such as:
 Code Review
 ~~~~~~~~~~~
 
-Contributions will not be merged until they've been code reviewed. You should
+Contributions will not be merged until they have been code reviewed. You should
 implement any code review feedback unless you strongly object to it. In the
 event that you object to the code review feedback, you should make your case
 clearly and calmly. If, after doing so, the feedback is judged to still apply,
@@ -205,7 +205,7 @@ be aware of the following things when filing bug reports:
    to check whether your bug report or feature request has been mentioned in
    the past. Duplicate bug reports and feature requests are a huge maintenance
    burden on the limited resources of the project. If it is clear from your
-   report that you would have struggled to find the original, that's ok, but
+   report that you would have struggled to find the original, that's okay, but
    if searching for a selection of words in your issue title would have found
    the duplicate then the issue will likely be closed extremely abruptly.
 2. When filing bug reports about exceptions or tracebacks, please include the

diff --git a/docs/dev/philosophy.rst b/docs/dev/philosophy.rst
@@ -13,7 +13,7 @@ Management Style
 
 `Dan Ryan <http://github.com/techalchemy>`__, `Tzu-ping Chung <https://github.com/uranusjr>`__, and `Nate Prewitt <https://github.com/nateprewitt>`__ are the core contributors.
 They are responsible for triaging bug reports, reviewing pull requests and ensuring that Kenneth is kept up to speed with developments around the library.
-The day-to-day managing of the project is done by the core contributors. They are responsible for making judgements about whether or not a feature request is
+The day-to-day managing of the project is done by the core contributors. They are responsible for making judgments about whether or not a feature request is
 likely to be accepted by Kenneth.
 
 Values

diff --git a/docs/diagnose.rst b/docs/diagnose.rst
@@ -29,7 +29,7 @@ usually one of the following locations:
 * ``%LOCALAPPDATA%\pipenv\pipenv\Cache`` (Windows)
 * ``~/.cache/pipenv`` (other operating systems)
 
-Pipenv does not install prereleases (i.e. a version with an alpha/beta/etc.
+Pipenv does not install pre-releases (i.e. a version with an alpha/beta/etc.
 suffix, such as *1.0b1*) by default. You will need to pass the ``--pre`` flag
 in your command, or set
 
@@ -124,7 +124,7 @@ for more information.
 ---------------------------------------------
 
 When you configure a supervisor program's ``command`` with ``pipenv run ...``, you
-need to set locale enviroment variables properly to make it work.
+need to set locale environment variables properly to make it work.
 
 Add this line under ``[supervisord]`` section in ``/etc/supervisor/supervisord.conf``::
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -84,7 +84,7 @@ User Testimonials
 - Automatically finds your project home, recursively, by looking for a ``Pipfile``.
 - Automatically generates a ``Pipfile``, if one doesn't exist.
 - Automatically creates a virtualenv in a standard location.
-- Automatically adds/removes packages to a ``Pipfile`` when they are un/installed.
+- Automatically adds/removes packages to a ``Pipfile`` when they are installed or uninstalled.
 - Automatically loads ``.env`` files, if they exist.
 
 The main commands are ``install``, ``uninstall``, and ``lock``, which generates a ``Pipfile.lock``. These are intended to replace ``$ pip install`` usage, as well as manual virtualenv management (to activate a virtualenv, run ``$ pipenv shell``).

diff --git a/docs/install.rst b/docs/install.rst
@@ -71,7 +71,7 @@ Homebrew/Linuxbrew installer takes care of pip for you.
 ===================
 
 Pipenv is a dependency manager for Python projects. If you're familiar
-with Node.js' `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
+with Node\.js's `npm`_ or Ruby's `bundler`_, it is similar in spirit to those
 tools. While pip can install Python packages, Pipenv is recommended as
 it's a higher-level tool that simplifies dependency management for common use
 cases.
@@ -101,7 +101,7 @@ To upgrade pipenv at any time::
 ☤ Pragmatic Installation of Pipenv
 ----------------------------------
 
-If you have a working installation of pip, and maintain certain "toolchain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
+If you have a working installation of pip, and maintain certain "tool-chain" type Python modules as global utilities in your user environment, pip `user installs <https://pip.pypa.io/en/stable/user_guide/#user-installs>`_ allow for installation into your home directory. Note that due to interaction between dependencies, you should limit tools installed in this way to basic building blocks for a Python workflow like virtualenv, pipenv, tox, and similar software.
 
 To install::
 

diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
@@ -0,0 +1,87 @@
+appdir
+ascii
+asdf
+backport
+bashrc
+bundler
+canonicalized
+cmder
+Cmder
+codebase
+Conda
+CPython
+cygwin
+Deduplicate
+Devops
+eval
+filesystem
+Homebrew
+ini
+installable
+Integrations
+io
+js
+json
+Linuxbrew
+lockfile
+macOS
+Makefile
+manpage
+metadata
+mingw
+misconfiguration
+misconfigured
+msys
+natively
+npm
+parallelization
+parsers
+pathlib
+pexpect
+pipenv
+Pipenv
+Pipfile
+Pipfiles
+piptools
+powershell
+Powershell
+pre
+py
+pyenv
+pypi
+PyPI
+pythonfinder
+resolvers
+runtime
+runtimes
+sayers
+scandir
+sha
+stateful
+subdirectory
+subprocess
+subprocesses
+subshell
+supervisord
+tox
+Tox
+tracebacks
+triaging
+txt
+unicode
+uninstallation
+unnesting
+untrusted
+url
+urls
+UTF
+vcs
+vendored
+Vendored
+venv
+virtualenv
+virtualenvs
+Virtualenv
+Virtualenvs
+zsh
+zshrc
diff --git a/news/4209.doc.rst b/news/4209.doc.rst
@@ -0,0 +1 @@
+Added functionality to check spelling in documentation and cleaned up existing typographical issues.