[docs] update docs on configuration (#243)

.github/workflows/check-docs.yml

@@ -21,7 +21,7 @@ jobs:
       - uses: conda-incubator/setup-miniconda@v3
         with:
           environment-file: docs/env.yml
-          activate-environment: pydistscheck-docs
+          activate-environment: pydistcheck-docs
           miniforge-variant: Mambaforge
           use-mamba: true
       - name: build docs

.github/workflows/smoke-tests.yml

@@ -32,7 +32,7 @@ jobs:
           fetch-depth: 1
       - uses: conda-incubator/setup-miniconda@v3
         with:
-          activate-environment: pydistscheck-tests
+          activate-environment: pydistcheck-tests
           miniforge-variant: Mambaforge
           use-mamba: true
           python-version: ${{ matrix.python_version }}

.github/workflows/unit-tests.yml

@@ -56,7 +56,7 @@ jobs:
           fetch-depth: 1
       - uses: conda-incubator/setup-miniconda@v3
         with:
-          activate-environment: pydistscheck-tests
+          activate-environment: pydistcheck-tests
           miniforge-variant: Mambaforge
           use-mamba: true
           python-version: ${{ matrix.python_version }}

docs/_static/defaults.toml

@@ -1,10 +1,32 @@
 [tool.pydistcheck]
 
+# List of checks to ignore.
+# See https://pydistcheck.readthedocs.io/en/latest/check-reference.html for
+# a complete list.
 ignore = []
+
+# Set to true to print a summary of the distribution, like its total
+# size and largest files.
 inspect = false
+
+# If more than this many files is found in the distribution,
+# pydistcheck reports a 'too-many-files' check failure.
 max_allowed_files = 2000
+
+# If the distribution is larger than this size (compressed),
+# pydistcheck reports a 'distro-too-large-compressed' check failure.
+#
+# See 'pydistcheck --help' for available units.
 max_allowed_size_compressed = '50M'
+
+# If the distribution is larger than this size (uncompressed),
+# pydistcheck reports a 'distro-too-large-compressed' check failure.
+#
+# See 'pydistcheck --help' for available units.
 max_allowed_size_uncompressed = '75M'
+
+# List of fnmatch.fnmatchcase() patterns to be compared to directories
+# in the distribution.
 unexpected_directory_patterns = [
     '*/.appveyor',
     '*/.binder',
@@ -15,6 +37,9 @@ unexpected_directory_patterns = [
     '*/.pytest_cache',
     '*/.mypy_cache'
 ]
+
+# List of fnmatch.fnmatchcase() patterns to be compared to files
+# in the distribution.
 unexpected_file_patterns = [
     '*/appveyor.yml',
     '*/.appveyor.yml',

docs/configuration.rst

@@ -3,12 +3,14 @@ Configuration
 
 This page describes how to configure ``pydistcheck``.
 
-``pydistscheck`` resolves different sources of configuration in the following order.
+``pydistcheck`` combines different sources of configuration in the following order.
 
 1. default values
-2. :ref:`pyproject-toml`
+2. :ref:`pyproject-toml` (or custom TOML file passed via ``--config``)
 3. :ref:`cli-arguments`
 
+Configuration found further down the list overrides configuration found earlier in the list.
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents:

docs/env.yml

@@ -1,5 +1,5 @@
 ---
-name: pydistscheck-docs
+name: pydistcheck-docs
 channels:
   - nodefaults
   - conda-forge

src/pydistcheck/cli.py

@@ -69,7 +69,9 @@ class ExitCodes:
     is_flag=True,
     show_default=False,
     default=_Config.inspect,
-    help="print diagnostic information about the distribution",
+    help=(
+        "Print a summary of the distribution, like its total size and largest files."
+    ),
 )
 @click.option(  # type: ignore[misc]
     "--max-allowed-files",