tuitorial: terminal-based interactive code tutorials 📚

Sat, 04 Jan 2025 00:00:00 +0000

While trying to demonstrate my pipefunc package (a tool for automating computational pipelines), I hit a common presentation problem: how do you effectively walk through code without endless repetition?

Traditional presentation tools like PowerPoint force you to copy-paste the same code snippets multiple times just to highlight different parts. Jupyter notebooks are great for self-paced learning but clunky for live presentations (too much text that the viewer will try to read). I needed something that would let me define code once and create multiple views highlighting different aspects.

So, during the holiday season, I did what any reasonable developer would do: procrastinated on my actual work and built a new tool instead!

What is tuitorial? #

tuitorial is a Python package that lets you create interactive, terminal-based code tutorials where you define the code ONCE, then create steps that highlight different parts based on rules (like regex patterns or line numbers). No more copy-paste presentations!

Key Features #

Write code once: Define your code once, then create multiple views highlighting different aspects
Rich highlighting options: From simple literal matches to complex regex patterns
Interactive navigation: Intuitive keyboard controls for stepping through tutorials
Beautiful terminal UI: Powered by Textual for a polished look
Flexible configuration: Choose between Python API or YAML format
Development mode: Live reloading for quick iterations

See It in Action #

Here’s a demo of tuitorial explaining pipefunc - a package that lets you create computational pipelines with automatic parallelization, caching, and dependency management:

Who Should Use This? #

While tuitorial isn’t for everyone, it’s perfect for:

Developers giving technical presentations
Teachers explaining code concepts
Teams creating interactive documentation
Anyone who loves terminal-based tools

Getting Started #

pip install tuitorial

Check out the documentation for examples and detailed usage instructions.

Final Thoughts #

Building tuitorial was a lot of fun! While it may not replace PowerPoint for your next business presentation, it offers a unique approach to code demonstrations that I hope others will find useful.

Try it out and let me know what you think!

markdown-code-runner 📝

Thu, 05 Dec 2024 00:00:00 +0000

(See my intro post)

Documentation should be as close to the code as possible - that’s the principle of “information locality.” But how do you keep code examples and their outputs in sync? Enter markdown-code-runner, a tool that executes code blocks within Markdown files and updates their output in-place!

📖 Origin Story #

While maintaining various open source and work projects, I found myself constantly updating README or Wiki files with new command outputs, updated tables, and fresh examples. This manual process was error-prone and tedious. Instead of using external templating files or more advanced documentation generators like Sphinx and Quarto (which are often overkill for single-page projects), I wanted something simpler: code and its output living together in the same Markdown file, always in sync.

🔧 Technical Highlights #

Executes code blocks (Python and Bash) within Markdown files
Updates outputs in-place while preserving the original file structure
Supports hidden code blocks for generating content without showing the code
Works with any language by using file code blocks and bash execution
Zero external dependencies
GitHub Actions integration for automatic README updates
Preserves Markdown spec compatibility by hiding code in HTML comments ()

📊 Impact #

97 GitHub stars
Used in many of my other projects for auto-generating:
- Command-line help texts
- API documentation
- Example outputs
- Data tables
Helps maintain “information locality” - everything needed is in one file
Enables dynamic documentation that stays up-to-date automatically

🎯 Challenges and Solutions #

Parsing Markdown without breaking its structure
Supporting multiple programming languages
Making it work seamlessly with GitHub Actions
Handling complex outputs (tables, images, etc.)
Maintaining backward compatibility with existing Markdown files

💡 Lessons Learned #

Documentation is best when it’s close to what it documents
Automation should be invisible - the tool shouldn’t change how you write Markdown
Sometimes the simplest solution (using HTML comments) is the best
Good documentation tools should make maintaining docs easier, not harder
Auto-generated content should be clearly marked as such

Want to keep your documentation always in sync? Check out markdown-code-runner on GitHub!

#OpenSource #Python #Documentation #DevTools #Programming

Documentation | Bas Nijholt

tuitorial: terminal-based interactive code tutorials 📚

What is tuitorial? #

Key Features #

See It in Action #

Who Should Use This? #

Getting Started #

Final Thoughts #

markdown-code-runner 📝

📖 Origin Story #

🔧 Technical Highlights #

📊 Impact #

🎯 Challenges and Solutions #

💡 Lessons Learned #