Add: Vale prose linter with basic config - pycon sprint!

Setup Vale (prose linter) with a minimal unobtrusive configuration

Author: lwasser

.gitignore

@@ -8,5 +8,4 @@ __pycache__
 *notes-from-review.md
 *.idea*
 # Grammar / syntax checkers
-.vale.ini
 styles/

.pre-commit-config.yaml

@@ -31,6 +31,15 @@ repos:
     - id: codespell
       additional_dependencies:
         - tomli
+      exclude: >
+        (?x)^(
+            .*vale-styles.*
+        )$
+
+  - repo: https://github.com/errata-ai/vale
+    rev: v3.4.2
+    hooks:
+    - id: vale
 
 ci:
     autofix_prs: false

.vale.ini

@@ -0,0 +1,32 @@
+# Configuration file for using Vale in the python-package-guide repository
+#
+# To disable checks on parts of a MarkDown or HTML file, delimit the section
+# using these HTML comments:
+#     to disabled Vale checks after this line: <!-- vale off -->
+#     to enable Vale checks after this line: <!-- vale on -->
+#
+# To disable checks based on MarkDown scope, see IgnoredScopes.
+# To disable checks on certain HTML elements, see IgnoredClasses.
+#
+# More information about the configuration can be found here:
+# https://vale.sh/docs/topics/config
+
+
+# Path to the styles directory, where style rules are defined
+StylesPath = vale-styles
+
+# Path to a dictionary folders inside the StylesPath config subdirectory. This
+# folder can contain two files, accept.txt and reject.txt, with one word per
+# line. These words will be used to check for spelling mistakes in addition to
+# the internal dictionary, if the 'Vale' ruleset is enabled (see below)
+# See https://vale.sh/docs/topics/vocab/#folder-structure for more details
+Vocab = sample
+
+
+# Checks are defined in sections by file type, like the one below for
+# MarkDown. In each section you can enable groups of style rules, defined in folders
+# inside the StylesPath directory.
+# Use 'Vale' to enable the internal style rules and checks.
+
+[*.md]
+BasedOnStyles = package-guide-test

conf.py

@@ -135,6 +135,7 @@
     "styles/write-good/README.md",
     "styles/*",
     ".pytest_cache/README.md",
+    "vale-styles/*",
 ]
 
 # For sitemap generation

index.md

@@ -71,7 +71,7 @@ The first round of our community-developed, how to create a Python package tutor
 
 * [What is a Python package?](/tutorials/intro)
 * [Make your code installable](/tutorials/installable-code)
-* [Publish your package to (test) PyPi](/tutorials/publish-pypi)
+* [Publish your package to (test) PyPI](/tutorials/publish-pypi)
 * [Publish your package to conda-forge](/tutorials/publish-conda-forge)
 
 :::

package-structure-code/publish-python-package-pypi-conda.md

@@ -104,7 +104,7 @@ exist in the `defaults` Anaconda channel.
 
 :::{figure-md} pypi-conda-channels
 
-<img src="../images/python-pypi-conda-channels.png" alt="Graphic with the title Python package repositories. Below it says Anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. the top row says conda channels. next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to pypi. and test pypi. a testbed server for you to practice. " width="700px">
+<img src="../images/python-pypi-conda-channels.png" alt="Graphic with the title Python package repositories. Below it says Anything hosted on PyPI can be installed using pip install. Packaging hosted on a conda channel can be installed using conda install. Below that there are two rows. the top row says conda channels. next to it are three boxes one with conda-forge, community maintained; bioconda and then default - managed by the anaconda team. Below that there is a row that says PyPI servers. PyPI - anyone can publish to PyPI. and test PyPI. a testbed server for you to practice. " width="700px">
 
 Conda channels represent various repositories that you can install packages from. Because conda-forge is community maintained, anyone can submit a recipe there. PyPI is also a community maintained repository. Anyone can submit a package to PyPI and test PyPI. Unlike conda-forge there are no manual checks of packages submitted to PyPI.
 :::

package-structure-code/python-package-distribution-files-sdist-wheel.md

@@ -91,14 +91,14 @@ represent on your PyPI landing page. These classifiers also allow users to sort
 ```
 
 :::{figure-md} build-workflow
-<img src="../images/python-package-development-process.png" alt="Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. an arrow to the right takes you to a build distribution files box. that box leads you to either publishing to testpypi or the real pypi. from pypi you can then connect to conda-forge for an automated build that sends distributions from pypi to conda-forge. " width="700px">
+<img src="../images/python-package-development-process.png" alt="Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. an arrow to the right takes you to a build distribution files box. that box leads you to either publishing to TestPyPI or the real PyPI. from PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge. " width="700px">
 
 You need to build your Python package in order to publish it to PyPI (or Conda). The build process organizes your code and metadata into a distribution format that can be uploaded to PyPI and subsequently downloaded and installed by users. NOTE: you need to publish a sdist to PyPI in order for conda-forge to properly build your package automatically.
 :::
 
 :::{figure-md}
 
-<img src="../images/python-build-package/pypi-metadata-keywords-license.png" alt="This screenshot shows the metadata on pypi for the xclim package. on it you can see the name of the license, the author and maintainer names keywords associated with the package and the base python version it requires which is 3.8." width="400px">
+<img src="../images/python-build-package/pypi-metadata-keywords-license.png" alt="This screenshot shows the metadata on PyPI for the xclim package. on it you can see the name of the license, the author and maintainer names keywords associated with the package and the base python version it requires which is 3.8." width="400px">
 
 PyPI screenshot showing metadata for the xclim package.
 :::

pyproject.toml

@@ -21,7 +21,13 @@ dependencies = [
     "sphinxext-opengraph",
     "sphinx-inline-tabs",
     # for project cards
-    "matplotlib"
+    "matplotlib",
+]
+
+[project.optional-dependencies]
+dev = [
+    # for checking style rules
+    "vale"
 ]
 
 [tool.hatch.build.targets.wheel]

tutorials/intro.md

@@ -321,7 +321,7 @@ Then you can create a conda-forge recipe using the [Grayskull](https://github.co
 [You will learn more about the conda-forge publication process here.](publish-conda-forge.md)
 
 :::{figure-md} publish-package-pypi-conda-overview
-<img src="../images/tutorials/publish-package-pypi-conda.png" alt="Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. an arrow to the right takes you to a build distribution files box. that box leads you to either publishing to testPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." width="700px">
+<img src="../images/tutorials/publish-package-pypi-conda.png" alt="Graphic showing the high level packaging workflow. On the left you see a graphic with code, metadata and tests in it. Those items all go into your package. Documentation and data are below that box because they aren't normally published in your packaging wheel distribution. an arrow to the right takes you to a build distribution files box. that box leads you to either publishing to TestPyPI or the real PyPI. From PyPI you can then connect to conda-forge for an automated build that sends distributions from PyPI to conda-forge." width="700px">
 
 In the image above, you can see the steps associated with publishing
 your package on PyPI and conda-forge. Note that the distribution files that PyPI requires are the [sdist](#python-source-distribution) and [wheel](#python-wheel) files. Once you are ready to make your code publicly installable, you can publish it on PyPI. Once your code is on PyPI it is straight forward to then publish to conda-forge. You create a recipe using the Grayskull package and then you open a pr in the conda-forge recipe repository. You will learn more about this process in the [conda-forge lesson](/tutorials/publish-conda-forge).

tutorials/publish-pypi.md

@@ -295,7 +295,7 @@ will remember them.
 ## Install your package from TestPyPI
 
 Once your package upload is complete, you can install it from
-TestPYPI. You can find the installation instructions on the TestPyPI
+TestPyPI. You can find the installation instructions on the TestPyPI
 landing page for your newly uploaded package.
 
 :::{figure-md} testpypi-landing-page