Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README: document simplest usage pattern #2638

Merged
merged 4 commits into from
Dec 12, 2022
Merged

README: document simplest usage pattern #2638

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
84d25b8
README: document simplest usage pattern
waldyrious Dec 10, 2022
4d838ca
Revert unintended change
waldyrious Dec 10, 2022
9ad70ee
README: indent text that refers to a code block above
waldyrious Dec 12, 2022
c8d5597
Revert indentation changes and apply reviewer suggestion
waldyrious Dec 12, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 38 additions & 11 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,43 +34,66 @@ You can use ``pip`` to install codespell with e.g.:
Usage
-----

For more in depth info please check usage with ``codespell -h``.
Below are some simple usage examples to demonstrate how the tool works.
For exhaustive usage information, please check the output of ``codespell -h``.

Run codespell in all files of the current directory:

.. code-block:: sh

codespell

Run codespell in specific files or directories (specified via their names or glob patterns):

.. code-block:: sh

codespell some_file some_dir/ *.ext

Some noteworthy flags:

.. code-block:: sh

codespell -w, --write-changes

The ``-w`` flag will actually implement the changes recommended by codespell. Not running with ``-w`` flag is the same as with doing a dry run. It is recommended to run this with the ``-i`` or ``--interactive`` flag.
..

The ``-w`` flag will actually implement the changes recommended by codespell. Not running with ``-w`` flag is the same as with doing a dry run. It is recommended to run this with the ``-i`` or ``--interactive`` flag.
waldyrious marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: sh

codespell -I FILE, --ignore-words=FILE

The ``-I`` flag can be used for a list of certain words to allow that are in the codespell dictionaries. The format of the file is one word per line. Invoke using: ``codespell -I path/to/file.txt`` to execute codespell referencing said list of allowed words. **Important note:** The list passed to ``-I`` is case-sensitive based on how it is listed in the codespell dictionaries.
..

The ``-I`` flag can be used for a list of certain words to allow that are in the codespell dictionaries. The format of the file is one word per line. Invoke using: ``codespell -I path/to/file.txt`` to execute codespell referencing said list of allowed words. **Important note:** The list passed to ``-I`` is case-sensitive based on how it is listed in the codespell dictionaries.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These new added indentations will make it render incorrectly. You can "view file" to see how these are rendered as block quotes now -- clicking it:

Screenshot 2022-12-12 at 9 24 05 AM

Will show the problem:

Screenshot 2022-12-12 at 9 24 35 AM

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, I was afraid this would be the case — GitHub's preview function didn't work when I tried editing the file in the web interface, so I used a different rST renderer, that indented blockquotes but didn't style them differently from the surrounding text otherwise.

I do think that indenting the text in relation to the associated code block (without marking it as a blockquote) would be ideal in order to convey the proper structure of the document, since in most other cases a code block follows the text that describes it. However, I couldn't figure out a way to simply indent text using rST, so the only other option I can think of is to rephrase these passages so they can be placed before the associated code block. But that would be beyond the scope of this PR, so I'll simply revert those changes. Let me know if you have any other ideas, though!


.. code-block:: sh

codespell -L word1,word2,word3,word4

The ``-L`` flag can be used to allow certain words that are comma-separated placed immediately after it. **Important note:** The list passed to ``-L`` is case-sensitive based on how it is listed in the codespell dictionaries.
..

The ``-L`` flag can be used to allow certain words that are comma-separated placed immediately after it. **Important note:** The list passed to ``-L`` is case-sensitive based on how it is listed in the codespell dictionaries.

.. code-block:: sh

codespell -x FILE, --exclude-file=FILE

Ignore whole lines that match those in ``FILE``. The lines in ``FILE`` should match the to-be-excluded lines exactly.
..

Ignore whole lines that match those in ``FILE``. The lines in ``FILE`` should match the to-be-excluded lines exactly.

.. code-block:: sh

codespell -S, --skip=

Comma-separated list of files to skip. It accepts globs as well. Examples:
..

* to skip .eps & .txt files, invoke ``codespell --skip="*.eps,*.txt"``
Comma-separated list of files to skip. It accepts globs as well. Examples:

* to skip directories, invoke ``codespell --skip="./src/3rd-Party,./src/Test"``
* to skip .eps & .txt files, invoke ``codespell --skip="*.eps,*.txt"``

* to skip directories, invoke ``codespell --skip="./src/3rd-Party,./src/Test"``


Useful commands:
Expand All @@ -79,14 +102,18 @@ Useful commands:

codespell -d -q 3 --skip="*.po,*.ts,./src/3rdParty,./src/Test"

List all typos found except translation files and some directories.
Display them without terminal colors and with a quiet level of 3.
..

List all typos found except translation files and some directories.
Display them without terminal colors and with a quiet level of 3.

.. code-block:: sh

codespell -i 3 -w

Run interactive mode level 3 and write changes to file.
..

Run interactive mode level 3 and write changes to file.

We ship a collection of dictionaries that are an improved version of the one available
`on Wikipedia <https://en.wikipedia.org/wiki/Wikipedia:Lists_of_common_misspellings/For_machines>`_
Expand Down