References

Sometimes it might be useful to create a link to a table, an image, a code block or a chapter in the HTML document. Pyreball enables creation of such links with ease through Reference class.

Specifically, one can create a reference object by calling pb.Reference(). This object can be then passed to a function that creates a table (print_table()), a figure (print_figure()), a code block (print_code_block()), or a heading (print_h1(), ..., print_h6()). Each such function then creates a target for the link. To create a source, just retrieve the string representation of the reference (i.e. use __str__() method), or invoke a call on the reference object (i.e. use __call__() method).

The following snippet demonstrates a very simple usage of a reference object.

import pandas as pd

import pyreball as pb

ref = pb.Reference("My Table")
pb.print(f"It is possible to create a link {ref} before the target...")
pb.print_table(pd.DataFrame({"a": [1, 2], "b": [3, 4]}), reference=ref)
pb.print(f"and also link {ref} after the target.")
pb.print(f"It is also possible to create {ref('link with custom text')}.")

The code above creates a reference object with default link text My Table and the reference object is assigned to the table. The code also creates three instances of the same link pointing to the table. __str__() method uses the default string that we passed to the Reference constructor. The last link was created by __call__() method, which takes a parameter that is used to override the default link text.

When default link text is not provided through the constructor, Pyreball uses table numbers as texts for links pointing to tables. The same is applied for links pointing to figures or code blocks. In case of headings, the default link text would be the text of the heading itself.

The artificial example below demonstrates some of these features.

import matplotlib.pyplot as plt
import numpy as np
import pandas as pd
import seaborn as sns

import pyreball as pb

pb.set_title("References to Figures and Tables")

ref_ch_1 = pb.Reference()

pb.print_h1("Tables", reference=ref_ch_1)

N = 10
np.random.seed(1)
df = pd.DataFrame({"x": np.arange(1, N + 1), "y": np.random.random(N) * 4 + 3})
pb.print_table(df, caption="A data table.", index=False)

img_reference = pb.Reference()
table_ref = pb.Reference()
code_block_ref = pb.Reference()
pb.print_div(
    f"It is also possible to create references to tables, figures and code blocks. "
    f"For example, Table {table_ref} shows sortable columns, "
    f"Fig. {img_reference} displays a scatterplot, "
    f"and Source Code {code_block_ref} shows a trivial function. "
    f"Each reference has a default text to be displayed, "
    f"but this text can be overriden by using {pb.code('__call__()')} "
    f"method on the reference when pasting it into the text. "
    f"For example, here is a link to {img_reference('Scatterplot')}."
)
pb.print_table(
    df,
    caption="A sortable table with a reference",
    reference=table_ref,
    sortable=True,
    index=False,
)

pb.print_table(
    df,
    caption="A table sorted by y column",
    sorting_definition=[(df.columns.get_loc("y"), "asc")],
    index=False,
)

pb.print_h1("Charts")

fig, ax = plt.subplots()
sns.scatterplot(x="x", y="y", ax=ax, data=df)
ax.set(xlabel="x", ylabel="y")
pb.print_figure(fig, caption="A figure with a reference.", reference=img_reference)

pb.print_div(
    f"Note that you can use the references in your text multiple times, "
    f"see again the reference to Table {table_ref} and Fig. {img_reference}. "
    f"Of course, we cannot assign a single reference to multiple tables or figures. "
    f"Last, but not least, one can use reference to Chapter {ref_ch_1}. "
    f"Again, we can override the text and create a link to {ref_ch_1('First Chapter')}."
)

pb.print_h1("Code Blocks")

pb.print_code_block(
    'def greet():\n    print("hi")',
    caption="An example of code block.",
    reference=code_block_ref,
)

Note

Creating references explicitly through the constructor of Reference class allows us to use the reference object even before the target object is created. This would not be possible if the references were created by functions like print_table().