codespell-project / codespell

check code for common misspellings
GNU General Public License v2.0
1.86k stars 471 forks source link

README: unclarity to do with 'pyproject.toml' #3493

Open LinuxOnTheDesktop opened 1 month ago

LinuxOnTheDesktop commented 1 month ago

The following is very hard to parse.

Codespell will also check in the current directory for a pyproject.toml (or a path can be specified via --toml ) file, and the [tool.codespell] entry will be used, but only if the tomli package is installed for versions of Python prior to 3.11.

The main problem is a scope-ambiguity (or at least something like that). For, what does the 'only if' clause qualify? For instance, if I have Python <3.11, can I use a .toml file at all?

DimitriPapadopoulos commented 1 month ago

Indeed, that's a convoluted sentence. Could you suggest a better alternative?

LinuxOnTheDesktop commented 1 month ago

I am afraid that I cannot. For, I do not know what the original sentence means. If you were to convey to me the various things that the sentence intends, then I could rewrite it. Yet, if you do that, then you yourself have gone part of the way already to rewriting the sentence!

bwitt commented 1 month ago

I think it means:

Codespell will also check in the current directory for a pyproject.toml file (or a path specified via --toml), and the [tool.codespell] entry will be used. This works automatically if using Python >= 3.11, but requires the tomli package to be installed for Python <3.11.

DimitriPapadopoulos commented 1 month ago

Exactly. If you think about it, that's the only interpretation that makes sense.

LinuxOnTheDesktop commented 1 month ago

bwitt's formulation is an improvement. Further improvement is possible and desirable. How then about the following?

A yet further form of configuration file is possible, namely, configuration via 'TOML' file. This way of configuring codespell requires Python >= 3.11 or else the package called 'tomli'. The configuration file can be called pyproject.toml and reside in the current directory. Alternatively one can pass a full path via codespell --toml. In either case, the configuration entry within the file must be called [tool.codespell]. Here is an example [the example, I mean, that follows immediately in the existing README].

    Still: the plethora of configuration methods is making things complex. Perhaps what is really needful is a set of subheadings, one per type of file, and, under each subheading, a table presenting each type of file. Each table would have fields that include: