Edit on GitHub

math_demo

This is a small demo module showing how pdoc renders $\LaTeX$ when invoked as pdoc --math!

Using Math in Docstrings

Note that docstrings work like regular strings, so backslashes are treated as escape characters. You can either escape a backslash with a second backslash:

def foo():
    """docstring with $\\frac{x}{y}$."""

or prefix your docstring with an "r" so that you have a raw string where backslashes are not processed:

def foo():
    r"""raw docstring with $\frac{x}{y}$."""

Advanced Usage

pdoc uses MathJax's MathJax's in-browser renderer by default. Please note that while pdoc generally strives to be self-contained, these resources are included from MathJax's CDN. You can create a math.html.jinja2 file in your pdoc template directory to override the default implementation.

Example

 1r'''
 2This is a small demo module showing how pdoc renders $\LaTeX$ when invoked as `pdoc --math`!
 3
 4# Using Math in Docstrings
 5
 6Note that docstrings work like regular strings, so backslashes are treated as escape characters.
 7You can either escape a backslash with a second backslash:
 8
 9
10```python
11def foo():
12    """docstring with $\\frac{x}{y}$."""
13```
14
15or prefix your docstring with an "r" so that you have a
16[raw string](https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals)
17where backslashes are not processed:
18
19```python
20
21def foo():
22    r"""raw docstring with $\frac{x}{y}$."""
23```
24
25# Advanced Usage
26
27pdoc uses MathJax's MathJax's in-browser renderer by default. Please note that while pdoc
28generally strives to be self-contained, these resources are included from MathJax's CDN.
29You can create a `math.html.jinja2` file in your pdoc template directory to override the
30[default implementation](https://github.com/mitmproxy/pdoc/blob/main/pdoc/templates/math.html.jinja2).
31
32# Example
33'''
34import math
35
36
37def binom_coef(n: int, k: int) -> int:
38    """
39    Return the number of ways to choose $k$ items from $n$ items without repetition and without order.
40
41    Evaluates to $n! / (k! * (n - k)!)$ when $k <= n$ and evaluates to zero when $k > n$.
42    """
43    return math.comb(n, k)
44
45
46def long_formula():
47    r"""
48    $$
49        \Delta =
50        \Delta_\text{this} +
51        \Delta_\text{is} +
52        \Delta_\text{a} +
53        \Delta_\text{very} +
54        \Delta_\text{long} +
55        \Delta_\text{formula} +
56        \Delta_\text{that} +
57        \Delta_\text{does} +
58        \Delta_\text{not} +
59        \Delta_\text{fully} +
60        \Delta_\text{fit} +
61        \Delta_\text{on} +
62        \Delta_\text{the} +
63        \Delta_\text{screen}
64    $$
65    """
def binom_coef(n: int, k: int) -> int:
38def binom_coef(n: int, k: int) -> int:
39    """
40    Return the number of ways to choose $k$ items from $n$ items without repetition and without order.
41
42    Evaluates to $n! / (k! * (n - k)!)$ when $k <= n$ and evaluates to zero when $k > n$.
43    """
44    return math.comb(n, k)

Return the number of ways to choose $k$ items from $n$ items without repetition and without order.

Evaluates to $n! / (k! * (n - k)!)$ when $k <= n$ and evaluates to zero when $k > n$.

def long_formula():
47def long_formula():
48    r"""
49    $$
50        \Delta =
51        \Delta_\text{this} +
52        \Delta_\text{is} +
53        \Delta_\text{a} +
54        \Delta_\text{very} +
55        \Delta_\text{long} +
56        \Delta_\text{formula} +
57        \Delta_\text{that} +
58        \Delta_\text{does} +
59        \Delta_\text{not} +
60        \Delta_\text{fully} +
61        \Delta_\text{fit} +
62        \Delta_\text{on} +
63        \Delta_\text{the} +
64        \Delta_\text{screen}
65    $$
66    """

$$ \Delta = \Delta_\text{this} + \Delta_\text{is} + \Delta_\text{a} + \Delta_\text{very} + \Delta_\text{long} + \Delta_\text{formula} + \Delta_\text{that} + \Delta_\text{does} + \Delta_\text{not} + \Delta_\text{fully} + \Delta_\text{fit} + \Delta_\text{on} + \Delta_\text{the} + \Delta_\text{screen} $$