%reload_ext rubberize
import pint
ureg = pint.UnitRegistry()Annotations
Annotations allow explanatory text to appear alongside rendered calculations.
Inside %%tap cells, comments are treated as annotations rather than ignored code. When the cell is rendered, these comments appear as explanatory text in the calculation sheet.
%%tap
# Beam span
L = 6 * ureg.m
# Uniform load
w = 12 * (ureg.kN / ureg.m)
# Maximum moment
M = w * L**2 / 8Beam span
\( \displaystyle L = 6\ \mathrm{m} \)
Uniform load
\( \displaystyle w = 12\ \mathrm{kN} / \mathrm{m} \)
Maximum moment
\( \displaystyle M = \frac{w\,L^{2}}{8} = \frac{\left( 12\ \mathrm{kN} / \mathrm{m} \right)\,\left( 6\ \mathrm{m} \right)^{2}}{8} = 54.00\ \mathrm{kN}\,\mathrm{m} \)
Comments written on their own line appear as explanatory text associated with the calculation that follows.
Inline comments behave slightly differently. When a comment appears on the same line as a calculation, it is rendered alongside the resulting expression.
%%tap
L = 6 * ureg.m # Beam span
w = 12 * (ureg.kN / ureg.m) # Uniform load
M = w * L**2 / 8 # Maximum moment\( \displaystyle L = 6\ \mathrm{m} \)
Beam span
\( \displaystyle w = 12\ \mathrm{kN} / \mathrm{m} \)
Uniform load
\( \displaystyle M = \frac{w\,L^{2}}{8} = \frac{\left( 12\ \mathrm{kN} / \mathrm{m} \right)\,\left( 6\ \mathrm{m} \right)^{2}}{8} = 54.00\ \mathrm{kN}\,\mathrm{m} \)
Maximum moment
In this case, the annotation is displayed side by side with the rendered mathematics.
Config Options
Comments that contain options and shortcuts (those starting with @) are interpreted as configuration directives and are not rendered as annotations.
The rules for how these options are applied—whether inline on a line of code or as line comments affecting subsequent lines—are described in Customizing Rubberize and in the Config Reference.
Markdown
Annotation text can be formatted using Markdown. Rubberize uses Python-Markdown to render Markdown content.
This allows standard formatting such as headings, emphasis, lists, links, and other common Markdown features to be used within annotations.
Rubberize provides additional formatting features for annotation text. These features can be used within any annotation and may be combined with standard Markdown formatting.
Smaller Text
Text enclosed in carets is rendered in a smaller style.
%%tap
# The value is approximate ^rounded to three significant figures^.The value is approximate rounded to three significant figures.
Inline Line Breaks
A double backslash can be used to insert an inline line break within annotation text.
This is especially useful for inline annotations, where a longer explanation may need to be split across multiple lines when rendered.
%%tap
a = 420 # First line of text. \\ Second line of text.\( \displaystyle a = 420 \)
First line of text.
Second line of text.
Second line of text.
Inline Rubberize
Annotations may include inline Rubberize expressions using double curly braces.
Any expression placed inside {{ ... }} is parsed and rendered using Rubberize, allowing mathematical expressions to appear directly within annotation text.
%%tap
a = 2
b = 5
# The sum is {{ a + b # @nodef }}.\( \displaystyle a = 2 \)
\( \displaystyle b = 5 \)
The sum is \( \displaystyle 2 + 5 = 7 \).
Tables
The built-in tables extension of Python-Markdown in enabled, which allows simple tables to be constructed.
%%tap @res
a, b, c = (2, 5, 7)
# | Name | Value |
# |-------|-------|
# | a | {{a}} |
# | b | {{b}} |
# | c | {{c}} |\( \displaystyle a,\, b,\, c = \left( 2,\, 5,\, 7 \right) \)
| Name | Value |
|---|---|
| a | \( \displaystyle 2 \) |
| b | \( \displaystyle 5 \) |
| c | \( \displaystyle 7 \) |
Alert Boxes
Rubberize also supports four GitHub-style alert boxes.
%%tap
# > [!NOTE]
# > This is a **NOTE** alert box
# > [!WARNING]
# > This is a **WARNING** alert box
# > [!PASS]
# > This is a **WARNING** alert box
# > [!FAIL]
# > This is a **WARNING** alert boxThis is a NOTE alert box [!WARNING] This is a WARNING alert box [!PASS] This is a WARNING alert box [!FAIL] This is a WARNING alert box
Alert boxes can be used to highlight important notes, warnings, or additional information in the calculation sheet.
A second form is available for alerts that should appear only in the interactive document but not in printed output. When the marker begins with ? instead of !, the alert box is hidden when the document is printed (for example, when exporting to PDF).
%%tap
# > [?NOTE]
# > This is a **NOTE** alert boxThis can be useful for including internal reminders, notes, or other information that should not appear in a printed report.
Math Markings
Rubberize provides markings that visually emphasize rendered mathematical expressions. !mark for adding a vertical marker beside the expression, and !hi, !rhi, !yhi, !ghi, or !bhi for highlighting the expression.
They are included in inline comments.
%%tap
L = 6 * ureg.m # !mark Length of the span
w = 12 * (ureg.kN / ureg.m) # !hi Uniform load intensity
R = w * L / 2 # !rhi Reaction at each support
M = w * L**2 / 8 # !yhi Maximum bending moment
S = 150e3 * ureg.mm**3 # !ghi Section modulus of member
sigma = M / S # !bhi Resulting bending stress\( \displaystyle L = 6\ \mathrm{m} \)
Length of the span
\( \displaystyle w = 12\ \mathrm{kN} / \mathrm{m} \)
Uniform load intensity
\( \displaystyle R = \frac{w\,L}{2} = \frac{\left( 12\ \mathrm{kN} / \mathrm{m} \right)\,\left( 6\ \mathrm{m} \right)}{2} = 36.00\ \mathrm{kN} \)
Reaction at each support
\( \displaystyle M = \frac{w\,L^{2}}{8} = \frac{\left( 12\ \mathrm{kN} / \mathrm{m} \right)\,\left( 6\ \mathrm{m} \right)^{2}}{8} = 54.00\ \mathrm{kN}\,\mathrm{m} \)
Maximum bending moment
\( \displaystyle S = 150\,000.00\ \mathrm{mm}^{3} \)
Section modulus of member
\( \displaystyle \sigma = \frac{M}{S} = \frac{54.00\ \mathrm{kN}\,\mathrm{m}}{150\,000.00\ \mathrm{mm}^{3}} = \left( 3.60 \times 10^{-4} \right)\ \mathrm{kN}\,\mathrm{m} / \mathrm{mm}^{3} \)
Resulting bending stress
Similar to alert boxes, when the marker begins with ? instead of !, the markings are hidden when the document is printed.
%%tap
L = 6 * ureg.m # ?mark Length of the span
w = 12 * (ureg.kN / ureg.m) # ?hi Uniform load intensity
R = w * L / 2 # ?rhi Reaction at each support
M = w * L**2 / 8 # ?yhi Maximum bending moment
S = 150e3 * ureg.mm**3 # ?ghi Section modulus of member
sigma = M / S # ?bhi Resulting bending stress