Merge pull request #90 from UBC-MDS/prettier-docs

Enhance documentation

Author: yhouyang02

CHANGELOG.md

@@ -58,3 +58,17 @@ All notable changes to this project will be documented in this file.
 - Removed unused `docs` directory and Sphinx configuration
 - Removed unused GitHub Actions workflows
 - Removed Sphinx-related dependencies from `pyproject.toml`
+
+## [3.0.0] - 2026-02-02
+
+- Fixed errors when running examples in `README.md` and docstrings (with many thanks to the peer review)
+- Added step-by-step tutorials to `README.md` and documentation site (with many thanks to the peer review)
+- Added `CHANGELOG.md` to the documentation site
+- Added badges to `README.md` for PyPI version, build status, code quality, and documentation status
+- Added more words to `minidict` dataset
+- Added more in-line comments to user functions (with many thanks to the peer review)
+- Added work organization and retrospectives to `CONTRIBUTING.md`
+- Added GitHub Actions workflow for dynamic versioning
+- Added GitHub Actions workflow for previewing documentation site
+- Added GitHub Actions workflow for code coverage reporting
+- Removed redundant signs in the example code snippets in `README.md` (with many thanks to the peer review)

README.md

@@ -28,22 +28,40 @@ You can install this package into your preferred Python environment using pip:
 
 ```bash
 pip install -i https://test.pypi.org/simple/ wordguess
-``````
+```
+
+To use `wordguess` in your code, you can follow this full example that applies the built-in `minidict` dataset and all four main functions:
+
+```python
+# 1. Load the package with alias.
+import wordguess as wg
+```
 
-To use `wordguess` in your code:
+```python
+# 2. Get the string results of making three different guesses against the target "major". 
+result_hist = {}
+for word in ['whelp','might','madam']:
+    # As a player, we do not know the target word "major", 
+    # so we simulate getting the result:
+    result_hist[word] = wg.get_result('major', word)
+```
+
+```python
+# 3. Get the top three possible target words based on the result history. 
+# This may be used to provide hints to the player.
+wg.get_n_guesses(result_hist, n=3)
+```
 
 ```python
->>> from wordguess.get_result import get_result
->>> get_result("spark", "spoon")
+# 4. Get the overall score of guesses based on the results:
+results = list(result_hist.values())
+wg.get_score(results)
 ```
 
 ```python
->>> import wordguess as wg
->>> 
->>> result_hist = {}
->>> for word in ['whelp','might','madam']:
->>>     result_hist[word] = wg.get_result('major', word)
->>>     wg.get_n_guesses(result_hist, n=10)
+# 5. Convert the result of the last guess into a human-readable pattern.
+last_result = result_hist['madam']
+wg.result_to_pattern(last_result)
 ```
 
 ## Development

_quarto.yml

@@ -5,6 +5,7 @@ project:
     - LICENSE
     - CODE_OF_CONDUCT.md
     - CONTRIBUTING.md
+    - CHANGELOG.md
     - README.md
 
 website:
@@ -35,6 +36,8 @@ website:
         href: index.qmd
       - text: "API Reference"
         href: reference/index.qmd
+      - text: "Changelog"
+        href: CHANGELOG.md
       - text: "Contributing Guide"
         href: CONTRIBUTING.md
       - text: "Code of Conduct"

src/wordguess/_internals.py

@@ -566,6 +566,7 @@
     "harry",
     "sweep",
     "manor",
+    "slope",
     "guild",
     "foray",
     "altar",
@@ -635,5 +636,7 @@
     "exult",
     "candy",
     "might",
-    "spark"
+    "spark",
+    "apply",
+    "stare"
 ]

src/wordguess/get_n_guesses.py

@@ -116,6 +116,7 @@ def get_n_guesses(result_hist: dict, n: int = None, corpus: list = minidict) ->
     This function filters the given corpus of allowed words using the information
     contained in a result history. Each entry in the result history consists of
     a guessed word and its corresponding result string, where:
+
     - '0' indicates the letter is not present in the target word,
     - '1' indicates the letter is present but in the wrong position, and
     - '2' indicates the letter is correct and in the correct position.
@@ -130,22 +131,23 @@ def get_n_guesses(result_hist: dict, n: int = None, corpus: list = minidict) ->
     result_hist : dict
         A dictionary mapping previously guessed words to their
         corresponding result strings composed of '0', '1', and '2'.
-    n : int (optional)
+    n : int, optional
         The maximum number of valid guesses to return.
         If None, all valid guesses are returned.
-    corpus : list (optional)
+    corpus : list, optional
         A list of all allowed words to consider as possible targets.
 
     Returns
     -------
-    list: A list of words from the corpus that are consistent with the result history.
+    list
+        A list of words from the corpus that are consistent with the result history.
 
     Raises
     ------
     TypeError
-        If result_hist is not a dictionary.
-        If n is not a positive integer or None.
-        If corpus is not a list of strings.
+        If result_hist is not a dictionary;
+        if n is not a positive integer or None; or
+        if corpus is not a list of strings.
     ValueError
         If result_hist is internally inconsistent.
 
@@ -158,7 +160,6 @@ def get_n_guesses(result_hist: dict, n: int = None, corpus: list = minidict) ->
     >>> result_hist = {"crane": "01200", "sloth": "10020"}
     >>> get_n_guesses(result_hist, corpus=corpus)
     ['about', 'shout', 'mount']
-
     >>> get_n_guesses(result_hist, n=2, corpus=corpus)
     ['shout', 'mount']
     """

src/wordguess/get_result.py

@@ -11,26 +11,28 @@ def get_result(target: str, guess: str, corpus: list = minidict) -> str:
         The secret word that needs to be guessed.
     guess : str
         The word provided by the player to be compared against the target.
-    corpus : list (optional)
+    corpus : list, optional
         A collection of valid words used for validation.
         Defaults to `minidict`.
 
     Returns
     -------
     str
-        A string of digits representing the result for each letter:
-        - '0' : The letter does not exist in the target.
-        - '1' : The letter exists in the target but in a different position.
-        - '2' : The letter is in the correct position.
+        A string of digits representing the result for each letter, containing '0', '1', and '2'.
 
     Raises
     ------
     TypeError
         If target or guess are not strings.
     ValueError
-        If target and guess have different lengths.
-        If the target is not found in the corpus.
-        If the guess is not found in the corpus.
+        If target and guess have different lengths;
+        if the target is not found in the corpus; or
+        if the guess is not found in the corpus.
+
+    See Also
+    --------
+    get_n_guesses : A function that generates a list of possible valid guesses based on previous results.
+
     Examples
     --------
     >>> get_result("apple", "apply")

src/wordguess/get_score.py

@@ -24,7 +24,7 @@ def get_score(
 
     Parameters
     ----------
-    result : list of str
+    result : list
         A list containing the list of result. The result is a string
         with characters '0', '1', and '2' representing different guess outcomes.
 
@@ -46,9 +46,9 @@ def get_score(
     TypeError
         If result is not a list of strings or penalty is not a boolean.
     ValueError
-        If result strings contain invalid characters.
-        If result strings do not have the same length.
-        If any result string is empty.
+        If result strings contain invalid characters;
+        if result strings do not have the same length; or
+        if any result string is empty.
 
     Examples
     --------

src/wordguess/result_to_pattern.py

@@ -2,11 +2,12 @@ def result_to_pattern(result: str) -> str:
     """
     Convert a result string to a human-readable pattern of symbols.
 
-    This function maps each character in a result string to a corresponding colored square
-    symbol.
+    This function maps each character in a result string to a corresponding colored square symbol.
+
     - The character '0' maps to a dark grey square symbol,
     - The character '1' maps to a yellow square symbol and,
     - The character '2' maps to a green square symbol.
+
     The output is a string composed of UTF-8 colored square symbols.
 
     Parameters
@@ -16,7 +17,8 @@ def result_to_pattern(result: str) -> str:
 
     Returns
     -------
-    str: The corresponding human-readable string pattern composed of UTF-8 colored symbols.
+    str
+        The corresponding human-readable string pattern composed of UTF-8 colored symbols.
 
     Raises
     ------
@@ -27,13 +29,14 @@ def result_to_pattern(result: str) -> str:
 
     See Also
     --------
-    get_result : A function that generate the result string for a given guess against a target word.
+    get_result : A function that generates the result string for a given guess against a target word.
 
-    Example:
+    Examples
+    --------
     >>> result_to_pattern("01102")
-    "⬛🟨🟨⬛🟩"
+    '⬛🟨🟨⬛🟩'
     >>> result_to_pattern("0001221")
-    "⬛⬛⬛🟨🟩🟩🟨"
+    '⬛⬛⬛🟨🟩🟩🟨'
     """
     if not isinstance(result, str):  # checks that input is of `str` type
         raise TypeError(f"Expected the input to be of type str, got {type(result)}")