fixes after review

Author: krother

.claude/commands/sphinx_review.md

@@ -0,0 +1 @@
+Examine the repo, reviewing code and text for design weaknesses, bugs, unclear language, and outdated Python features. Assume Python 3.12. Write everything found into a file TODO.md.

CLAUDE.md

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Purpose
+
+This is a Sphinx documentation site — a collection of copy-paste Python library examples organized as a reference/tutorial book. Each library lives in its own subdirectory with a `README.rst` file and standalone `.py` example scripts.
+
+## Build Commands
+
+```bash
+# Build HTML documentation
+uv sync
+uv run make html
+```
+
+The built site goes to `build/html/`. Open `build/html/index.html` to preview locally.
+
+## Project Structure
+
+- **`index.rst`** — top-level table of contents, controls what appears in the docs
+- **`conf.py`** — Sphinx configuration (theme: furo, extensions: myst_parser, sphinx_design, sphinx_copybutton)
+- **`<library>/README.rst`** — documentation page for each library (RST format)
+- **`<library>/*.py`** — standalone example scripts included via `.. literalinclude::` directives
+- **`<library>/*.png`** — output images referenced with `.. figure::` directives
+- **`_static/`** — CSS and logo assets
+
+## Content Conventions
+
+Each library page follows this pattern:
+1. A question as the section heading (e.g., "How to draw a bar chart?")
+2. Brief description of the library
+3. Install instruction in a `.. code::` block
+4. One or more examples using `.. literalinclude:: script.py`
+5. Optional `.. figure:: image.png` showing expected output
+6. A `.. seealso::` block linking to official docs
+
+Example scripts should be **self-contained and runnable** — no shared utilities or imports from sibling directories.
+
+## Adding a New Library
+
+1. Create a subdirectory `<library>/`
+2. Write `<library>/README.rst` following the conventions above
+3. Add standalone `.py` example scripts
+4. Add the entry to `index.rst` under the appropriate section: `<library>/README.rst`
+5. Run `make html` to verify it builds without warnings
+
+## Formats
+
+- Documentation pages use **RST** (`.rst`), not Markdown — `myst_parser` is installed but RST is the primary format used
+- The `exclude_patterns` in `conf.py` excludes `README.md` (the GitHub-facing readme) and `learning_goals.md` files from the Sphinx build

PuLP/magic_square.py

@@ -1,5 +1,5 @@
 
-from pulp import *
+from pulp import LpProblem, LpMinimize, LpVariable, LpInteger, lpSum, LpStatus, value
 
 prob = LpProblem("PULPTEST", LpMinimize)
 
@@ -48,5 +48,4 @@
         for n in NUMBERS:
             if value(allocation[x][y][n]) == 1:
                 print(n, end=' ')
-                #print(x, y, n)
     print()

README.md

@@ -106,6 +106,6 @@ Thanks to Emely Henninger for finding a nasty bug in networkx!
 
 ## License
 
-© 2025 Dr. Kristian Rother (krother@academis.eu)
+© 2026 Dr. Kristian Rother (krother@academis.eu)
 
 The code is distributed under the conditions of the MIT License. See :::file LICENSE.TXT for details.

TODO.md

@@ -1,15 +1,5 @@
 
-   seaborn (external)](https://seaborn.pydata.org/) | a more powerful interface for matplotlib |
-   altair (external)](https://altair-viz.github.io/) | plotting library with JSON backend |
-   geopandas (external)](http://geopandas.org/) | plot DataFrames on maps |
-   panel (external)](http://panel.pyviz.org/) | create interactive plots |
-   CV2 (external)](https://docs.opencv.org/3.0-beta/doc/py_tutorials/py_tutorials.html) | processing camera images and movies |
-   milvus
-   narwhals
-   duckdb
-   
+# Review Findings
 
-playwright/README.md - not in toctree
-playwright/web_testing/README.rst - not in toctree
-re/exercises/regex_exercises.md - not in toctree
-sqlalchemy/README.md - not in toctree
+- **`index.rst` line 53** — `pathlib/README.rst # TODO`: the `pathlib/` directory does not exist, and toctree entries do not support inline comments. This causes a Sphinx build error.
+- **`moviepy/end_credits.py`** — uses `moviepy.editor` (MoviePy 1.x API, removed in 2.x) and `faker.Factory` (deprecated since Faker 4.0). Needs a full rewrite for MoviePy 2.x.

curses/README.rst

@@ -23,6 +23,6 @@ Run it from a terminal.
 
    It likely means that your window is too small.
 
-.. seealso::
+.. note::
 
    My first contact with curses was inspired by `manti_go <https://github.com/JoNiederhut/manti_go>`__ written by my course participants.

curses/pac.py

@@ -73,7 +73,7 @@ def pac_game(screen):
     player = 1, 1
     ghost = 9, 9
 
-    while player != ghost and any([row for row in level if "." in row]):
+    while player != ghost and any(row for row in level if "." in row):
         ghost = move_ghost(ghost, level)
         draw(level, player, ghost, screen, win)
         if direction := get_keyboard(win):

email/send_email.py

@@ -1,6 +1,6 @@
 
 import smtplib
-from email.mime.text  import MIMEText
+from email.mime.text import MIMEText
 
 class MailAccount:
     """
@@ -10,7 +10,7 @@ def __init__(self, server,  login,  password,  sender_email, \
                  sender_name, use_tls=False):
         self.server = server
         self.login = login
-        self.password = password
+        self.password = password   # Caution: use environment variable in production
         self.mail = sender_email
         self.sender = '"%s" <%s>'%(sender_name, sender_email)
         self.use_tls = use_tls
@@ -25,7 +25,7 @@ def send_email(self, recipient_email, subject, body):
         msg = message.as_string()
 
         server = smtplib.SMTP(self.server)
-        server.set_debuglevel(1)
+        server.set_debuglevel(1)  # Caution: lots SMTP traffic - do not use in production
 
         if self.use_tls: # deliberately starts tls if using TLS
             server.ehlo()