Getting Started

Getting Started#

This guide will help you install chartbook and create your first project.

Installation#

Prerequisites#

  • Python 3.8 or higher

  • pip package manager

chartbook has two main use cases with different installation methods:

For Data Scientists (using chartbook in your projects)#

Install the minimal package for loading data from ChartBook pipelines:

pip install chartbook

This gives you access to the data loading API:

from chartbook import data
df = data.load(pipeline="fred_charts", dataframe="interest_rates")

For Generating Documentation (CLI)#

Recommended (isolated installation, no dependency pollution):

# Install globally via pipx
pipx install chartbook

# Or run without installing
pipx run chartbook build
uvx chartbook build

Alternative (if you prefer pip, installs Sphinx dependencies):

pip install "chartbook[sphinx]"

Development Installation#

chartbook uses Hatch for package management:

pip install hatch
git clone <your-repo-url>
cd chartbook
hatch shell

# Install with all dependencies (sphinx + dev tools)
pip install -e ".[dev]"

Important: The quotes around ".[dev]" are required when installing with extras locally.

Common installation patterns:

pip install -e .              # Core only (data loading)
pip install -e ".[sphinx]"    # Core + Sphinx CLI
pip install -e ".[all]"       # All optional features (sphinx)
pip install -e ".[dev]"       # Everything (all + pytest)

Tip: Use pip install -e ".[all]" for development when you want all features but don’t need testing tools. This is ideal for contributors working on documentation or CLI features.

Working with Project Paths#

chartbook provides the chartbook.env module for consistent path handling across your project. This is especially useful when your scripts run from different directories or in Jupyter notebooks.

Finding the Project Root#

The get_project_root() function automatically locates your project root by searching for marker files like .git, pyproject.toml, or .env:

import chartbook

# Works from any subdirectory in your project
BASE_DIR = chartbook.env.get_project_root()
DATA_DIR = BASE_DIR / "_data"
OUTPUT_DIR = BASE_DIR / "_output"

Reading Environment Variables#

Use chartbook.env.get() to read configuration from .env files, environment variables, or command line arguments:

import chartbook

# Read from .env file or environment
username = chartbook.env.get("WRDS_USERNAME")
api_key = chartbook.env.get("FRED_API_KEY", default="")

See the chartbook.env documentation for full details.

Quick Start Tutorial#

1. Create Your First Pipeline Project#

Create a new directory for your project and navigate to it:

mkdir my-analytics-project
cd my-analytics-project
git init  # Initialize git so chartbook can find project root

2. Create a Configuration File#

Create a chartbook.toml file to configure your project:

[config]
type = "pipeline"
chartbook_format_version = "0.0.6"

[site]
title = "My Analytics Project"
author = "Your Name"
copyright = "2025"
logo_path = ""
favicon_path = ""

[pipeline]
id = "MYPROJ"
pipeline_name = "My First Pipeline"
pipeline_description = "A demo pipeline for learning chartbook"
lead_pipeline_developer = "Your Name"
contributors = ["Your Name"]

3. Create Your First Chart#

Create the necessary directories:

mkdir -p _data _output docs_src/charts

Create a simple Python script to generate data (generate_data.py):

import pandas as pd
import numpy as np
import chartbook

# Get project root - works from any subdirectory
BASE_DIR = chartbook.env.get_project_root()
DATA_DIR = BASE_DIR / "_data"

# Generate sample data
dates = pd.date_range('2023-01-01', '2024-01-01', freq='D')
data = {
    'date': dates,
    'value1': np.cumsum(np.random.randn(len(dates))) + 100,
    'value2': np.cumsum(np.random.randn(len(dates))) + 100
}
df = pd.DataFrame(data)

# Save to parquet
df.to_parquet(DATA_DIR / 'sample_data.parquet')
print("Sample data generated!")

4. Create a Chart#

Create a chart using chartbook’s plotting utilities:

import chartbook
import pandas as pd

# Get project paths
BASE_DIR = chartbook.env.get_project_root()
DATA_DIR = BASE_DIR / "_data"
OUTPUT_DIR = BASE_DIR / "_output"

# Load the data
df = pd.read_parquet(DATA_DIR / 'sample_data.parquet')

# Create an interactive plot and save to files
result = chartbook.plotting.line(
    df,
    x='date',
    y=['value1', 'value2'],
    title='My First Chart',
)
result.save(chart_id="my_first_chart", output_dir=str(OUTPUT_DIR))
print("Chart created!")
print(result.paths)

5. Add Chart Documentation#

Create docs_src/charts/my_first_chart.md:

# My First Chart

This chart shows the relationship between value1 and value2 over time.

## Key Insights
- Both values show trending behavior
- The correlation between the series changes over time

## Data Sources
- Generated sample data for demonstration

6. Update Configuration#

Add the chart to your chartbook.toml:

[charts]

[charts.my_first_chart]
chart_name = "My First Chart"
short_description_chart = "Demo chart showing two time series"
dataframe_id = "sample_data"
topic_tags = ["Demo", "Time Series"]
data_frequency = "Daily"
units = "Index"
path_to_html_chart = "./_output/my_first_chart.html"
chart_docs_path = "./docs_src/charts/my_first_chart.md"

[dataframes]

[dataframes.sample_data]
dataframe_name = "Sample Data"
short_description_df = "Generated sample data for demonstration"
data_sources = ["Generated"]
path_to_parquet_data = "./_data/sample_data.parquet"
date_col = "date"

7. Generate Documentation#

Now generate your documentation website:

chartbook build -f ./docs

Open docs/index.html in your browser to see your generated site!

Next Steps#

Common Issues#

Module Not Found Error#

If you get import errors, make sure chartbook is installed in your current environment:

pip show chartbook

Permission Errors#

On Windows, you might need to run commands as administrator or adjust file permissions.

Sphinx Build Errors#

If documentation generation fails, check that all required files exist:

  • chartbook.toml in the project root

  • Chart HTML files in the paths specified

  • Documentation markdown files

Getting Help#

Contents