License

© DataJoint Inc., 2024-2025, All rights reserved.

This work is licensed under the CC BY 4.0 License. You may:

• share the content in any medium or format
• adapt, remix, transform, and build upon the material for any purpose

Provided that you:

• give appropriate credit and indicate if changes were made

DataJoint Book

Welcome to the DataJoint Book, a comprehensive introduction to relational database programming in the context of scientific computing and data science.

This book is built as an executable book, following the principles of the Executable Books Project, an international collaboration to build open source tools that facilitate publishing computational narratives using the Jupyter ecosystem.

The book is authored using MyST Markdown (Markedly Structured Text), an extensible, semantic, and community-driven flavor of markdown designed for scientific and computational narratives. MyST enables us to:

• Write rich, publication-quality content with enhanced markdown syntax
• Embed executable code cells and computational outputs directly in the documentation
• Generate interactive web pages and other output formats from the same source
• Maintain a single source of truth for documentation, examples, and executable content

This approach ensures that all code examples in the book are tested, up-to-date, and can be run directly by readers, bridging the gap between documentation and hands-on learning.

Running the Book with Dev Containers

This repository includes a Dev Container (Development Container) configuration that provides a pre-configured development environment with all necessary dependencies, tools, and extensions already set up. This eliminates the need to manually install Python, DataJoint, MyST, and other required packages on your local machine.

What is a Dev Container?

A Dev Container is a Docker-based development environment that runs inside a container but integrates seamlessly with your code editor (like Visual Studio Code or GitHub Codespaces). It ensures that everyone working on the book has an identical, reproducible environment, regardless of their operating system or local setup.

How to Use the Dev Container

Option 1: Using Visual Studio Code (Local)

1. Install Docker Desktop on your machine
2. Install Visual Studio Code
3. Install the Dev Containers extension in VS Code
4. Clone this repository and open it in VS Code
5. When prompted, click "Reopen in Container" (or use Command Palette: Dev Containers: Reopen in Container)
6. VS Code will build the container and reload the workspace inside it

Option 2: Using GitHub Codespaces (Cloud)

1. Navigate to this repository on GitHub
2. Click the green "Code" button
3. Select the "Codespaces" tab
4. Click "Create codespace on main"
5. GitHub will launch a cloud-based VS Code environment with the Dev Container already running

Once inside the Dev Container, you have access to all tools needed to build, edit, and execute the book's content, including Jupyter notebooks, Python with DataJoint, and MyST build tools.

Building and Deployment

Once you're working inside the Dev Container (see above), you can build and preview the book locally.

Building the Book

The MyST static site deployment instructions are provided here: https://mystmd.org/guide/deployment

To build and serve the book locally:

$ cd book
$ myst build --html
$ npx serve _build/html

This will:

1. Build the static HTML site from the MyST markdown and Jupyter notebook sources
2. Start a local web server (typically at http://localhost:3000)
3. Allow you to preview the book in your browser exactly as it will appear when deployed

Automatic Deployment

The book is automatically published to https://dimitri-yatsenko.github.io/datajoint-book using GitHub Actions.

Every time changes are pushed to the main branch, a GitHub Actions workflow:

1. Builds the book using MyST
2. Deploys the generated HTML to GitHub Pages
3. Makes the updated book immediately available online

You can monitor the build and deployment status via the badge at the top of this README or by viewing the Actions tab in the repository. This automated CI/CD pipeline ensures that the published version always reflects the latest content in the repository.

Manual Workflow Execution

You can also manually trigger the "Build and Deploy DataJoint Book" workflow from the GitHub Actions interface:

1. Navigate to the Actions tab in the repository
2. Select the "Build and Deploy DataJoint Book" workflow from the left sidebar
3. Click the "Run workflow" button (on the right side)
4. Select the branch you want to run the workflow on (typically main)
5. Click "Run workflow" to start the build and deployment process

This is useful when you want to rebuild and redeploy the book without making a new commit, or when testing workflow changes on a feature branch.

Contributions

We welcome and appreciate your contributions to this book, whether as a reviewer or as a contributor. All contributions will be gratefully acknowledged. You may suggest modifications by submitting an issue in the main GitHub repository for this book. For more substrantial contributions and collaborations, including co-authorship and publications, please contact Dimitri Yatsenko.