Skip to content

docs(examples): standardize tutorial, notebooks, and root examples - #1777

Open
rafvasq wants to merge 2 commits into
generative-computing:mainfrom
rafvasq:docs/tutorials-notebooks-root-standardize
Open

rafvasq wants to merge 2 commits into
generative-computing:mainfrom
rafvasq:docs/tutorials-notebooks-root-standardize

Conversation

@rafvasq

@rafvasq rafvasq commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Pull Request

Issue

Towards #1746

Description

Standardizes tutorial/, notebooks/, the root docs/examples/README.md, and the root example scripts.

Docstrings

  • Kept the original titles and descriptions. Scripts that had no docstring use their README description as the title.
  • Added Prerequisites: (where they're required) and Usage: blocks.

READMEs

  • tutorial/ and notebooks/: the file lists are now ## Examples tables using the original descriptions, with a "See Also" section linking the two directories and the first tutorial.
  • Removed sections:
    • tutorial/README.md: "Running the Examples", "Key Concepts Covered", "Differences from Notebooks", "Relationship to Notebooks".
    • notebooks/README.md: "Benefits of Notebooks", "Corresponding Python Files", "Tips".
    • Run instructions now live in each script's Usage: block. The .py ↔ .ipynb mapping can be read from the two ## Examples tables.

Other fixes

  • Root README.md:
    • Added the missing sampling/ and primitives/ entries.
    • Fixed the tutorial/simple_email.py link, which was pointing at the directory.
  • tutorial/table_mobject.py: added the missing uv pip install pandas prerequisite.
  • tutorial/document_mobject.py: removed an unused IBM_GRANITE_4_HYBRID_MICRO import.

Testing

  • Tests added to the respective file if code was changed
  • New code has 100% coverage if code was added
  • Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

  • AI coding assistants used

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

  • Component
  • Requirement
  • Sampling Strategy
  • Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
Assisted-by: IBM Bob
@rafvasq
rafvasq requested a review from a team as a code owner October 29, 2026 15:59
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Oct 29, 2026

@planetf1 planetf1 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Docs-only change; three small notes inline. CI is green at 7fbfbfd8a and example collection is unchanged (the same 15 items as main).

The README section removals match #1746. Nothing project-specific is lost: run instructions moved into each script's Usage: block, and the .py ↔ .ipynb mapping is now derivable from the two tables for all nine files.

Separately, not for this PR: README.md:278 still shows the older python <script> / uv run <script> form.

- `instruct_validate_repair.py` ↔ `instruct_validate_repair.ipynb`
- etc.

## Running the Examples

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It may be useful for reviewers if the PR body mentioned the removed sections: "Running the Examples", "Key Concepts Covered", "Differences from Notebooks" and "Relationship to Notebooks" here, and "Benefits of Notebooks", "Corresponding Python Files" and "Tips" in notebooks/README.md. Nothing links to the removed anchors.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Added to desc

Comment thread docs/examples/README.md

**New to Mellea?** Start here:
1. [tutorial/simple_email.py](tutorial/) - Your first Mellea program
1. [tutorial/simple_email.py](tutorial/simple_email.py) - Your first Mellea program

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same fix needed one more time, though this line is pre-existing: 245 still has [tutorial/sentiment_classifier.py](tutorial/), so it points at the directory rather than the script.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed


Prerequisites:
ollama serve
ollama pull granite4.2:3b

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment at line 14 still reads # INFO: this line will download IBM's Granite 4 Micro 3B model., which now contradicts this line — the default is granite4.2:3b. Worth deleting or updating while you're in here.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Removed comment

Remove stale Granite 4 Micro download comment from simple_email.py and point the sentiment_classifier.py link at the script.

Assisted-by: IBM Bob
Signed-off-by: Rafael Vasquez <rafvasq21@gmail.com>
@rafvasq
rafvasq requested a review from planetf1 October 30, 2026 18:50

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants