Skip to content

Comments

Docs#68

Draft
tammoippen wants to merge 55 commits intomasterfrom
docs
Draft

Docs#68
tammoippen wants to merge 55 commits intomasterfrom
docs

Conversation

@tammoippen
Copy link
Owner

@tammoippen tammoippen commented Jan 19, 2026

No description provided.

github-advanced-security[bot]
github-advanced-security bot found potential problems Jan 19, 2026
View reviewed changes
github-advanced-security[bot]
github-advanced-security bot found potential problems Jan 20, 2026
View reviewed changes
docs/generate_docs.py
docstring = ast.get_docstring(tree)
if docstring:
return docstring.strip().split("\n")[0] # First line only
except SyntaxError:

Check notice

Code scanning / CodeQL

Empty except Note documentation

'except' clause does nothing but pass and there is no explanatory comment.

Copilot Autofix

AI about 1 month ago

In general, an empty except should either (a) be removed so the exception propagates, or (b) handle the error meaningfully—logging, transforming, or otherwise recording it—and/or clearly document why it is intentionally ignored.

Here, the existing logic is: try to parse the module and get its docstring; if that fails due to SyntaxError, fall back to scanning for the first comment. We should keep that behavior, but make the except block non-empty. The best low-impact fix is to add a short comment explaining the intentional fallback, and optionally log the syntax error at a low verbosity level using the standard library logging module.

Concretely, in docs/generate_docs.py:

  • Add an import for logging near the top.
  • Replace the except SyntaxError: pass block with an except SyntaxError: that either:
    • logs the failure via logging.debug(...) and then continues, and
    • includes a comment indicating that the function will fall back to comment-based description.

This preserves all existing behavior while satisfying the rule and aiding debugging.

Suggested changeset 1
docs/generate_docs.py

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -10,6 +10,7 @@
 from ansi2html.style import get_styles
 
 import plotille
+import logging
 
 conv = Ansi2HTMLConverter()
 
@@ -78,7 +79,8 @@
         if docstring:
             return docstring.strip().split("\n")[0]  # First line only
     except SyntaxError:
-        pass
+        # Invalid Python source; fall back to extracting the first comment instead.
+        logging.debug("Failed to parse source for description due to SyntaxError; using comment fallback.")
 
     # Fall back to first comment
     lines = source_code.split("\n")
EOF
@@ -10,6 +10,7 @@
from ansi2html.style import get_styles

import plotille
import logging

conv = Ansi2HTMLConverter()

@@ -78,7 +79,8 @@
if docstring:
return docstring.strip().split("\n")[0] # First line only
except SyntaxError:
pass
# Invalid Python source; fall back to extracting the first comment instead.
logging.debug("Failed to parse source for description due to SyntaxError; using comment fallback.")

# Fall back to first comment
lines = source_code.split("\n")
Copilot is powered by AI and may make mistakes. Always verify output.
docs/generate_docs.py
# Start of license
if "MIT License" in line:
in_license = True
start_index = i

Check notice

Code scanning / CodeQL

Unused local variable Note documentation

Variable start_index is not used.

Copilot Autofix

AI about 1 month ago

In general, an unused local variable that is not intentionally unused should be removed to avoid confusion and keep the code clean. If the assignment’s right-hand side has important side effects, only the variable binding should be removed, not the expression itself.

In this specific case, start_index is assigned but never used. The logic to strip the license header already works by returning "\n".join(lines[i:]), which uses the loop index i directly. Therefore, the best fix is to delete the start_index variable entirely and adjust the nearby comment so it accurately describes the behavior. Concretely:

  • Remove the line start_index = 0.
  • Remove the assignment start_index = i inside the "MIT License" branch.
  • Update the comment on line 146 so it no longer refers to start_index and instead describes that we return everything from the first non-comment, non-blank line after the license.

No new imports, methods, or definitions are needed.

Suggested changeset 1
docs/generate_docs.py

Autofix patch

Autofix patch
Run the following command in your local git repository to apply this patch
cat << 'EOF' | git apply
diff --git a/docs/generate_docs.py b/docs/generate_docs.py
--- a/docs/generate_docs.py
+++ b/docs/generate_docs.py
@@ -130,7 +130,6 @@
     if "# The MIT License" in source_code:
         # Find the end of the license block (first non-comment/non-blank line after license)
         in_license = False
-        start_index = 0
 
         for i, line in enumerate(lines):
             stripped = line.strip()
@@ -138,12 +137,11 @@
             # Start of license
             if "MIT License" in line:
                 in_license = True
-                start_index = i
                 continue
 
             # End of license block (first non-comment, non-blank line)
             if in_license and stripped and not stripped.startswith("#"):
-                # Remove everything from start_index to just before this line
+                # Return everything from this line onward (after the license header)
                 return "\n".join(lines[i:])
 
         # If we didn't find the end, remove first 23 lines (typical license length)
EOF
@@ -130,7 +130,6 @@
if "# The MIT License" in source_code:
# Find the end of the license block (first non-comment/non-blank line after license)
in_license = False
start_index = 0

for i, line in enumerate(lines):
stripped = line.strip()
@@ -138,12 +137,11 @@
# Start of license
if "MIT License" in line:
in_license = True
start_index = i
continue

# End of license block (first non-comment, non-blank line)
if in_license and stripped and not stripped.startswith("#"):
# Remove everything from start_index to just before this line
# Return everything from this line onward (after the license header)
return "\n".join(lines[i:])

# If we didn't find the end, remove first 23 lines (typical license length)
Copilot is powered by AI and may make mistakes. Always verify output.
tammoippen and others added 28 commits February 2, 2026 14:38
@tammoippen
Add comprehensive documentation system implementation plan
c631cef
@tammoippen @claude
Add Brython compatibility validation test
3c0631d 
Creates a browser-based test environment to validate that plotille
can run in Brython (Python in the browser) for interactive documentation.

Setup:
- Added brython as dev dependency
- Created test-brython directory with Brython installation
- Added plotille package for browser use
- Integrated AnsiUp library for ANSI color rendering

Test page features:
- Runs Olympic Rings example (multiple colors)
- Captures stdout with ANSI color codes
- Converts ANSI to HTML using AnsiUp ES6 module
- Displays colored output in amber phosphor terminal aesthetic

Results:
✓ plotille imports successfully in Brython
✓ Canvas and Figure operations work correctly
✓ ANSI color codes render properly in browser
✓ Braille characters display correctly
✓ Performance is acceptable for interactive use

This validates the feasibility of interactive browser-based examples
for the documentation system implementation plan.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Document Brython validation test results
bbd42a9 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Remove debug logs and disable Brython debug mode
6fbe285 
- Removed FORCE_COLOR environment variable (not needed with isatty)
- Removed Python console.log debug statements
- Removed JavaScript console.log messages
- Disabled Brython debug mode to prevent verbose logging

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Update README - FORCE_COLOR not needed
006dc74 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Use Makefile for test environment setup, ignore generated files
a4a7123 
- Remove all generated files from git (Lib/, brython.js, ansi_up.js, etc.)
- Add .gitignore for test-brython directory
- Create Makefile with targets: setup, clean, serve, test
- Copy plotille source directly instead of using brython add_package
  (avoids trying to install numpy/PIL in browser)
- Update README with Makefile instructions

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Restore Olympic Rings test page
1edf2c5 
The index.html was accidentally replaced with the default 'Hello' page.
Restored the full Olympic Rings example with color rendering.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
Add MkDocs and documentation dependencies
d5e0f44
@tammoippen
Add basic MkDocs configuration
379f160
@tammoippen
Enable doctest in pytest configuration
508f83d
@tammoippen
Add example analysis script with tests
3a97f29
@tammoippen
Add build artifacts to gitignore
431b1dc
@tammoippen
add lock file
d45df83
@tammoippen
Add example categorization logic
8c0a313
@tammoippen
Add example execution and output capture
5be0e64
@tammoippen
Add static example pre-rendering
3c3f8e0
@tammoippen
Add markdown generation templates for examples
ba5fa6a
@tammoippen @claude
Add category page generation
87a62e1 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add home page generation
7682d12 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add amber phosphor terminal theme CSS
6e58a58 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
Add comprehensive implementation review with fixes
81e6804
@tammoippen @claude
Fix color contrast, filter unwanted examples, add hero plot, update nav
5a09f49 
- Fix color contrast in terminal.css with !important rules for dark backgrounds
- Skip __init__.py and performance_example.py from documentation
- Strip MIT license headers from example code and descriptions
- Add hero sine wave plot to home page
- Update navigation to include Cookbook section

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add Brython runtime integration
b8f6ee2 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add plotille source copying for Brython access
468b861 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add CodeMirror setup with textarea enhancement
9fdb00f 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
Add Phase 6-7 implementation review with critical fixes
5d83fd3
@tammoippen @claude
Fix build errors and complete Task 7.2
8020b98 
- Fix IsADirectoryError in generate_docs.py by handling None output paths
- Complete Task 7.2: Implement proper Brython execution with output capture
- Remove misleading CodeMirror check from codemirror-setup.js
- Remove test page from production navigation
- Exclude __pycache__ directories from plotille copy

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Fix Brython execution errors
e290b6f 
- Remove existing scripts before creating new ones (fixes duplicate ID error)
- Replace io.StringIO with custom OutputCapture class (Brython-compatible)
- Restore console.log immediately after brython() call
- Increase timeout to 150ms for reliable output capture

Fixes:
- TypeError: can't access property "__name__", locals is undefined
- Error: Found 2 scripts with the same id

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
tammoippen and others added 27 commits February 2, 2026 14:38
@tammoippen @claude
Fix Brython execution context error and add Makefile docs targets
3ad60b3 
Brython fix:
- Use exec() instead of indenting user code in try/finally block
- Prevents "can't access property __name__, locals is undefined" error
- Properly escapes code string for exec()

Makefile additions:
- Add 'make docs' target to generate documentation
- Add 'make docs-serve' target to generate and serve docs locally

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Rewrite Brython execution to use permanent Python script
1fabfb7 
The previous approach of creating dynamic script elements doesn't work
reliably with Brython - it causes "locals is undefined" errors when
trying to set up execution contexts.

New approach:
- Create permanent Python script (brython-executor.py) loaded on every page
- Script defines run_code() function exposed to JavaScript via window
- JavaScript simply calls this function with user code
- Proper output capture using custom OutputCapture class
- No dynamic script creation/destruction

Also:
- Add MkDocs template override (docs/overrides/main.html) to load Python script
- Update .gitignore to allow HTML files in docs/overrides/
- Set custom_dir in mkdocs.yml theme config

This matches the working pattern from test-brython/index.html.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Fix empty element ID error in Brython execution
b1601db 
The .output-content div doesn't have an ID, but we were passing
outputDiv.id to Python which was empty string. This caused:
- "Empty string passed to getElementById()"
- KeyError in Python when accessing document[output_element_id]

Fix:
- Get parent container by ID first
- Find .output-content child
- Dynamically assign ID to output content div if not present
- Pass that ID to Python

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Move plotille to Brython standard Lib/site-packages/ location
55ba795 
Fix ModuleNotFoundError by using Brython's standard module location.

Changes:
- Move plotille from docs/src/lib/ to docs/Lib/site-packages/
- Update copy script to use standard location
- Remove custom pythonpath from brython() initialization
- Brython automatically searches Lib/site-packages/ for modules

This matches the working pattern from test-brython/ setup.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Use local Brython installation instead of CDN
3f5118f 
The CDN version of Brython doesn't know about our local Lib/site-packages/
directory. Switch to local Brython files so modules can be found.

Changes:
- Install Brython locally in docs/ directory
- Update mkdocs.yml to use local brython.js and brython_stdlib.js
- Add docs-setup target to Makefile to install Brython
- Make docs target depend on docs-setup
- Add Brython files to .gitignore (they're generated and large: 7.5MB)

Usage:
  make docs-setup  # Install Brython (run once or after cleaning)
  make docs-serve  # Generate docs and serve (runs docs-setup automatically)

This matches the working pattern from test-brython/.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add isatty() and AnsiUp for colored output support
3a05514 
Add isatty() to OutputCapture to enable colors
Add AnsiUp library for ANSI-to-HTML conversion
Download ansi_up.js in docs-setup target

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Remove documentation build artifacts from git
d0547ac 
- Add docs/Lib/ and docs/assets/example-outputs/ to .gitignore
- Remove generated files from git tracking
- These files are regenerated by scripts/generate_docs.py

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Fix UX issues: code contrast, header readability, search results
20da306 
- Add syntax highlighting overrides for better code readability
  - Comments now muted tan instead of transparent
  - Operators and punctuation bright white
  - Keywords, strings, numbers properly colored
- Add header styling with solid black background
  - Header title and buttons bright amber for contrast
  - Search input properly styled
- Add search results styling
  - Proper amber color scheme
  - Limit excerpt height to 3 lines
  - Highlighted search terms readable
- Update code editor text color to bright white
  - Matches static code blocks
  - Better text rendering with antialiasing
  - Focus state with glow effect

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Fix remaining UX issues: colors, navigation, search
f075e40 
Code appearance:
- Mute white text in code blocks from #ffffff to #cccccc
- Update code editor text to match
- Mute operators/punctuation to match

Static example colors:
- Add ansi-output class to prerendered example outputs
- Add JavaScript to process ANSI codes with ansi_up on page load
- Static examples now show colored terminal output

Navigation:
- Fix sidebar navigation colors (Cookbook label, ToC)
- Add explicit amber colors with !important for visibility
- Fix header title to link to home page
- Override site_name block in template

Search results:
- Add comprehensive search result styling
- Force all text to use amber colors
- Add white-space: pre-wrap for code formatting
- Ensure highlighted terms are visible

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
rm build artifacts
d4af150
@tammoippen
some cleanup
168e1a0
@tammoippen
Add CSS simplification plan and implementation updates
1c7de37
@tammoippen @claude
Simplify to standard Material theme with minimal terminal styling
098dcf5 
Replace custom amber phosphor CRT theme (547 lines) with standard Material
theme and minimal terminal-only styling (117 lines). Terminal windows now use
Material CSS variables for consistent theming and proper light/dark mode support.

Changes:
- Remove global theme overrides (amber colors, CRT effects, scanlines, custom fonts)
- Style only terminal window components using Material variables
- Fix terminal output horizontal scrolling (white-space: pre with overflow-x: auto)
- Enable Material's navigation and search enhancements

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
use light and dark theme
100c4d5
@tammoippen @claude
Add mkdocstrings API reference configuration
81fe39a 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add doctest examples to plot() function
982af79 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add doctests to scatter(), hist(), and histogram() functions
4a78b41 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Configure site navigation structure
ce98748 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
Add comprehensive review of Phase 8-9 implementation
d685ea3
@tammoippen @claude
Fix navigation - remove non-existent cookbook pages
16df035 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add GitHub Actions workflow for documentation
8185acb 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add documentation testing checklist
67311ce 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add error styling for interactive examples
a3ae542 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen @claude
Add documentation link to README
40ad898 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
Add comprehensive review of Phase 11-12 implementation
e7ff0a6
@tammoippen @claude
Fix testing checklist to reflect actual cookbook pages
8e6b9e4 
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
@tammoippen
generate colored static plots
64fb81d
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@tammoippen