improve docs

docs/release-notes.md

@@ -1,6 +1,20 @@
-## 0.2.3, 0.2.2, 0.2.1 – 2025-01-20
+## 0.2.4 – 2025-01-21
 
-Minor site/docs fixes
+### Fixed
+
+- Minor site/docs fixes
+
+### Removed
+
+- `wordsiv/about.py`: no need to have this, package version in pyproject.toml
+
+## 0.2.1, 0.2.2, 0.2.3 – 2025-01-20
+
+### Fixed
+
+- Minor site/docs fixes
+
+## 0.2.0 - 2025-01-20
 
 ### Added
 

docs/snippets/suppress-warnings.py

@@ -11,7 +11,6 @@
 print(wsv.top_word(contains="BLAH"))
 
 # We can suppress these warnings by setting the logging level to ERROR:
-log = logging.getLogger("wordsiv")
 log.setLevel(logging.ERROR)
 
 # No warning this time!

docs/usage/filtering-words.md

@@ -1,11 +1,17 @@
 # Filtering Words
 
-All WordSiv word/text generation functions allow for filtering of the words
-from the Vocab
+WordSiv provides options for filtering the words that are used
+to [generate text](../generating-text):
 
-We demonstrate these arguments with `top_words()` for ease of understanding.
-These arguments are applicable to `word()`, `words()`, `top_word()`,
-`top_words()`, `sent()`, `sents()`, `para()`, `paras()`.
+- **Letter Case: [`case`](#filter-words-by-letter-case)**
+- **Word Length: [`wl`](#filter-words-by-word-length), [`min_wl`](#filter-words-by-word-length), [`max_wl`](#filter-words-by-word-length)**
+- **Substrings: [`startswith`](#word-starts-with-string-startswith), [`endswith`](#word-ends-with-string-endswith), [`contains`](#word-contains-strings-contains), [`inner`](#word-contains-inner-strings-inner)**
+- **Regular Expressions: [`regexp`](#filter-words-by-regex)**
+
+We demonstrate these arguments with `top_words()` so you can see what's
+happening without randomization. You can use these arguments for `word()`,
+`words()`, `top_word()`, `top_words()`, `sent()`, `sents()`, `para()`,
+`paras()`, `text()`.
 
 
 ## Filter Words by Letter Case
@@ -50,11 +56,11 @@ from the vocab.
 
 The `lc` option selects lowercase words from the Vocab (e.g. `"bread"`). It will
 *not* try to lowercase any words with capitals, since we wouldn't want to
-lowercase words like "Paris", "FAA" or "DDoS"
+lowercase words like `"Paris"`, `"FAA"`, or `"DDoS"`
 
 !!! Note "Why no `lc_og`?"
-    There is no need for a `lc_og` option, because `lc` only selects lowercase
-    words from the Vocab.
+    There is no need for a `lc_og` option, because `lc` **already** only selects
+    lowercase words from the Vocab.
 ```python
 --8<-- "case-lc.py"
 ```
@@ -109,11 +115,10 @@ vocab, transforming them to all caps (e.g. `"WWF", "BOAT", "PARIS"`).
 
 ### All Caps, No Case Change (`case='uc_og'`)
 
-The `cap_og` option selects all caps words from the Vocab (e.g. `"WWF"`). It
+The `uc_og` option selects all caps words from the Vocab (e.g. `"WWF"`). It
 does **not** capitalize any lowercase or capitalized words (like `case='uc'`
 does). This is useful for getting all caps words like acronyms.
 
-
 ```python
 --8<-- "case-uc-og.py"
 ```
@@ -138,32 +143,38 @@ the Vocab:
 
 ## Filter Words by Substrings
 
-Arguments `startswith`, `endswith`, `contains`, and `inner` let you select by
-words which contain specific substrings.
+Arguments **[`startswith`](#word-starts-with-string-startswith)**, **[`endswith`](#word-ends-with-string-endswith)**, **[`contains`](#word-contains-strings-contains)**, and **[`inner`](#word-contains-inner-strings-inner)** let you select words which contain specific substrings.
 
 ### Word Starts With String (`startswith`)
+
+Argument `startswith` matches words that have a specific glyph/string at the
+start of the word, *after* any case transformations may have occurred.
+
 ```python
 --8<-- "startswith.py"
 ```
 
 ### Word Ends With String (`endswith`)
 
+Argument `endswith` matches words that have a specific glyph/string at the
+end of the word, *after* any case transformations may have occurred.
+
 ```python
 --8<-- "endswith.py"
 ```
 
 ### Word Contains String(s) (`contains`)
-The `contains` argument looks for string(s) in the word, *after* any case
-transformations may have occurred.
+
+Argument `contains` matches words which contain specific string(s) in the word,
+*after* any case transformations may have occurred.
 
 ```python
 --8<-- "contains.py"
 ```
 
 ### Word Contains Inner String(s) (`inner`)
-The `inner` argument looks for string(s) in all characters of the word except
-for the first and last characters `word[1:-1]`, *after* any case
-transformations may have occurred.
+Argument `inner` matches words which contain specific string(s) in `word[1:-1]` (all
+but first and last glyphs), *after* any case transformations may have occurred.
 
 ```python
 --8<-- "inner.py"
@@ -197,10 +208,9 @@ the given filters. However, you can turn this off by adjusting the log level:
 
 ### Raising Errors
 
-Maybe you want your script to halt if there are no matching words, or
-want to catch the error and try something else. For this you can use the
-`raise_errors` option, which will raise `wordsiv.FilterError` exception if the
-filters return no word matches.
+Maybe you want your script to halt if there are no matching words, or want to
+catch the error and try something else. For this you can use the `raise_errors`
+option, which will raise `wordsiv.FilterError` if there are no word matches.
 
 ```python
 --8<-- "raise-errors.py"

docs/usage/generating-text.md

@@ -11,15 +11,15 @@ WordSiv provides several methods for generating text:
   [`paras()`](#multiple-paragraphs-paras)
 - **Text Block**: [`text()`](#text-block-text)
 
-For methods that generate text with probabilities (not `top_word()`, `top_words()`), there are some options for adjusting randomness of the output:
+For methods that generate text with probabilities (not `top_word()`, `top_words()`), there are options for adjusting the randomness of the output:
 
 - **[`seed`](#repeatable-output-seed)**: Make output repeatable (deterministic)
 - **[`rnd`](#word-randomness-rnd)**: Blend in fully random word selection with
   probability-based word selection
 - **[`rnd_punc`](#punctuation-randomness-rnd_punc)**: Blend in fully random
   punctuation selection with the default probability-based punctuation selection
 
-There are also these additional options:
+There are also additional options:
 
 - **[`numbers`](#mixing-in-numbers-numbers)**: Mix-in figures with the words
 - **[`punc`](#disabling-punctuation-punc)**: Optionally disable punctuation
@@ -124,10 +124,9 @@ also [word filter arguments](../filtering-words).
 
 ### Repeatable Output (`seed`)
 
-For reproducible results, you can set a random [seed] when initializing
-WordSiv or for individual function calls. This is essential if you want you want
-your proof to remain the same until you make changes to the code (or your
-glyphs).
+For reproducible results, you can set a random [seed] when initializing WordSiv
+or for individual function calls. This is essential if you want your proof to
+remain the same until you make changes to the code (or your glyphs).
 
 ```python
 --8<-- "seed.py"
@@ -160,9 +159,9 @@ The `rnd_punc` parameter controls how random the punctuation generation is. This
 is useful for getting less common punctuation that statistically doesn't occur
 all that often.
 
-- `rnd=0`: Use punctuation frequencies to select punctuation (default)
-- `rnd=1`: Completely random punctuation selection
-- `0<rnd<1`: Interpolation of punctuation frequency distribution and fully
+- `rnd_punc=0`: Use punctuation frequencies to select punctuation (default)
+- `rnd_punc=1`: Completely random punctuation selection
+- `0<rnd_punc<1`: Interpolation of punctuation frequency distribution and fully
   random distribution
 
 ```python