Skip to content

Jupytext Integration

This project supports Jupytext integration, enabling you to work with notebooks in both .ipynb and .py formats seamlessly.

What is Jupytext?

Jupytext is a plugin that enables you to:

  • Edit notebooks as Python scripts in your favorite text editor
  • Version control notebooks more effectively with text-based formats
  • Reduce merge conflicts when collaborating on notebooks
  • Pair notebooks and scripts so changes in either format sync automatically

Configuration

The project includes a pyproject.toml configuration file with Jupytext settings:

[tool.jupytext]
# Configuration for Jupytext - enables conversion between .ipynb and .py files

# Default formats to pair notebooks with
formats = "ipynb,py:percent"

# Notebook metadata to preserve
notebook_metadata_filter = "jupytext,-kernelspec,-language_info"

# Cell metadata to preserve  
cell_metadata_filter = "collapsed,scrolled,-execution,tags"

Supported Formats

The configuration supports these formats:

  • .ipynb: Standard Jupyter notebook format
  • .py:percent: Python script with # %% cell markers

Working with Jupytext Files

Creating a Paired Notebook

To create a new notebook that automatically pairs with a Python script:

# Create a Python script with Jupytext headers
jupytext --to notebook my_notebook.py

# Or create both formats at once
jupytext --set-formats ipynb,py:percent my_notebook.ipynb

Synchronizing Files

To sync changes between formats:

# Sync a specific file
jupytext --sync my_notebook.py

# Sync all paired files in a directory
jupytext --sync notebooks/

Converting Between Formats

# Convert Python script to notebook
jupytext --to notebook script.py

# Convert notebook to Python script  
jupytext --to py:percent notebook.ipynb

# Convert to multiple formats
jupytext --to ipynb,py:percent source.py

Cell Markers in Python Scripts

Jupytext uses special comments to mark cells in Python scripts:

# %% [markdown]
# This is a markdown cell
# You can write documentation here

# %%
# This is a code cell
import numpy as np
data = np.random.randn(100)

# %% [markdown]
# Another markdown cell with analysis results

Best Practices

1. Use Descriptive Cell Comments

# %% Load and preprocess data
import pandas as pd
df = pd.read_csv('data.csv')

# %% Exploratory data analysis
df.describe()

# %% Create visualizations
import matplotlib.pyplot as plt
plt.plot(df['x'], df['y'])

2. Keep Functions in Separate Cells

# %% Define utility functions
def preprocess_data(df):
    """Clean and prepare data for analysis"""
    return df.dropna()

# %% Apply preprocessing
clean_df = preprocess_data(raw_df)

3. Use Markdown for Documentation

# %% [markdown]
# ## Data Analysis Results
#
# The analysis shows:
# - Correlation between variables: 0.85
# - Statistical significance: p < 0.001
# - Sample size: 1000 observations

Integration with MkDocs

The MkDocs configuration automatically includes both .ipynb and .py files:

plugins:
  - mkdocs-jupyter:
      include: ["*.ipynb", "*.nb.py"]

This means you can:

  • Edit notebooks in Jupyter Lab/Notebook
  • Edit the same content as Python scripts in VS Code or other editors
  • Have changes automatically sync between formats
  • Include either format in your documentation

Example Files

See the Jupytext Example notebook for a practical demonstration of Jupytext features and capabilities.

Troubleshooting

Sync Issues

If files don't sync automatically:

# Force sync
jupytext --sync --force docs/notebooks/my_notebook.py

Format Issues

If conversion fails, check:

  1. Cell markers: Ensure # %% markers are properly formatted
  2. YAML headers: Verify notebook metadata is valid
  3. Configuration: Check pyproject.toml syntax

Build Issues

If notebooks don't render in MkDocs:

  1. File inclusion: Verify files are in the include pattern
  2. Navigation: Add files to the nav section in mkdocs.yml
  3. Execution: Check execute and allow_errors settings

Learn More