serena/docs/02_notebooks/01_library_example.ipynb

The role of notebooks

Notebooks are great for illustrations and examples that at the same time serve as integration tests. In this library template, notebooks will be executed with pytest (thus on every commit in your CI/CD pipeline). The results of the executions will be saved to the docs directory and converted to static websites through nbconvert. The static websites are then added to the documentation under the Guides and Tutorials section. These websites will be deployed to Github pages on push to develop.

Before running the notebook

Install the library and its dependencies with, if you haven't done so already

poetry install

from the root directory. You can also execute this command directly in the notebook but will need to reload the kernel afterwards

In [ ]:

# Here an illustration of your library
from serena.sample_package.sample_module import hello_stranger

hello_stranger()

Interactive Documentation

Note that since notebooks are rendered to html+javascript, you can embed interactive components like maps, videos and widgets into your documentation, as long as the interaction does not require re-execution of cells. Below an example of an interactive map created with plotly {cite}PlotlyMaps.

In [ ]:

# slightly adjusted example from https://plotly.com/python/mapbox-layers/
import pandas as pd
import plotly.express as px

us_cities = pd.read_csv(
    "https://raw.githubusercontent.com/plotly/datasets/master/us-cities-top-1k.csv",
)

fig = px.scatter_mapbox(
    us_cities,
    lat="lat",
    lon="lon",
    hover_name="City",
    hover_data=["State", "Population"],
    color_discrete_sequence=["fuchsia"],
    zoom=3,
    height=300,
)

fig.update_layout(mapbox_style="open-street-map", margin={"r": 0, "t": 0, "l": 0, "b": 0})
fig.show()

:style: unsrtalpha
:filter: docname in docnames