### Example Output

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/script_single.md

The expected standard output when running the StepUp boot process with the example scripts, showing the execution of planning and running phases.

```text
INFO:stepup.boot:Booting StepUp
INFO:stepup.boot:Planning
INFO:stepup.boot:Running
INFO:stepup.boot:Done

```

--------------------------------

### Regenerate Tutorial Example Outputs

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/development.md

Navigate to the docs directory and run 'stepup' to regenerate tutorial example outputs. Keep this process running for live preview while editing.

```bash
cd docs
stepup
```

--------------------------------

### Directory Structure for Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/static_named_glob.md

Sets up a sample directory and file structure for the named glob example. This layout simulates course chapters and sections, providing concrete files for the StepUp process.

```text
ch1/
ch1/sec1_1_introduction.txt
ch1/sec1_2_objectives.txt
ch2/
ch2/sec2_1_mathematical_requisites.txt
ch2/sec2_2_theory.txt
ch3/
ch3/sec3_1_applications.txt
ch3/sec3_2_discussion.txt
ch4/sec4_1_summary.txt
```

--------------------------------

### Example plan.py with Static File Declaration

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/static_files.md

A `plan.py` example demonstrating the declaration of `limerick.txt` as a static file and a subsequent step to process it.

```python
from stepup.core.api import static, runsh

static('limerick.txt')
runsh('cat limerick.txt | nl > numbered.txt')
```

--------------------------------

### Example: Out-of-Source Build with HERE and ROOT

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/here_and_root.md

This example demonstrates a minimal out-of-source build structure using StepUp. It involves creating source files and subdirectories, making scripts executable, and running StepUp to observe the output, showcasing the practical application of `HERE` and `ROOT` variables.

```python
{% include 'advanced_topics/here_and_root/source/plan.py' %}
```

```python
{% include 'advanced_topics/here_and_root/source/sub/plan.py' %}
```

```text
{% include 'advanced_topics/here_and_root/stdout.txt' %}
```

--------------------------------

### Start StepUp Build with `stepup boot`

Source: https://context7.com/reproducible-reporting/stepup-core/llms.txt

Initiate the StepUp build process, starting the UI, director, and worker processes. Use '-n' to specify the number of workers and '-w' or '-W' for interactive or automatic watch modes.

```bash
stepup boot -n 1
```

```bash
stepup boot -n 4
```

```bash
stepup boot -n 4 -w
```

```bash
stepup boot -n 4 -W
```

--------------------------------

### Install StepUp Core Package

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/installation.md

Use this command to install the main StepUp package. It is recommended to do this within a Python virtual environment.

```bash
pip install stepup
```

--------------------------------

### Example Output

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/distributed_plans.md

The expected output when running StepUp with distributed plans.

```text
{% include 'getting_started/distributed_plans/stdout.txt' %}
```

--------------------------------

### Install autocast using Cargo

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/asciinema/README.md

Install the autocast tool using cargo. Ensure that the ~/.cargo/bin directory is in your PATH.

```bash
cargo install autocast
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/development.md

After configuring the environment, run these commands to allow direnv, upgrade pip, and install the project with its development dependencies.

```bash
direnv allow
pip install -U pip
pip install -e .[dev]
```

--------------------------------

### Clone and Install StepUp Core Development Environment

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/development.md

Use these commands to clone the repository, set up pre-commit hooks, and create a virtual environment for development.

```bash
git clone git@github.com:reproducible-reporting/stepup-core.git
cd stepup-core
pre-commit install
python -m venv venv
```

--------------------------------

### Example Output from StepUp Execution

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/optional_steps.md

This is the expected standard output when running the StepUp plan with the data generation steps marked as optional.

```text
Running step: plot(r=2.8)
Plotting sequence for r=2.8 with 100 points.
Running step: plot(r=3.1)
Plotting sequence for r=3.1 with 100 points.
Running step: plot(r=3.5)
Plotting sequence for r=3.5 with 100 points.

```

--------------------------------

### Example Dataset Content

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/static_glob_conditional.md

Sample content for `dataset/bigfile.txt` used in the example. This file contains numbers that will be processed to calculate an average.

```text
1.0 2.0 3.0 4.0 5.0

```

--------------------------------

### Example Bash Command

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/script_single.md

Commands to make Python scripts executable and run the StepUp boot process with a specified number of workers.

```bash
chmod +x generate.py plan.py
stepup boot -n 1

```

--------------------------------

### StepUp Deferred Glob Output Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/static_deferred_glob.md

This is the expected screen output when running the StepUp plan with the deferred glob feature enabled. It shows which files are processed and made static.

```text
stepup boot -n 1

plan: dg:'*.txt;'
  step: copy('foo.txt', 'out.txt')

step: copy('foo.txt', 'out.txt')
  input: foo.txt
  output: out.txt

```

--------------------------------

### Example Terminal Output

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/amending_steps.md

This is the expected terminal output when running the StepUp example. It shows that `./step.py` initially exits early due to the missing `input.txt`. StepUp then schedules an optional step to generate `input.txt` and reruns `./step.py`.

```text
stepup: INFO: Bootstrapping...
stepup: INFO: Running step "./step.py"...
stepup: INFO: Step "./step.py" exited early because of missing input "input.txt".
stepup: INFO: Step "./step.py" will be rescheduled.
stepup: INFO: Running step "./step.py"...
Content of input.txt: This is the content of input.txt.
stepup: INFO: Step "./step.py" finished successfully.
stepup: INFO: All steps finished successfully.

```

--------------------------------

### Example Configuration File (config.json)

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/script_single.md

A JSON configuration file used by StepUp scripts to define parameters like the number of steps and frequency. This file can be shared across multiple scripts for consistency.

```json
{
  "nstep": 100,
  "freq": 1
}

```

--------------------------------

### Configuration File Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/render_jinja.md

A YAML configuration file used to provide variables for Jinja template rendering.

```yaml
{% include 'advanced_topics/render_jinja/config.yaml' %}
```

--------------------------------

### Install StepUp RepRep Extension

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/installation.md

Install the StepUp RepRep extension for reproducible reporting using this command. This should also be done within your Python virtual environment.

```bash
pip install stepup-reprep
```

--------------------------------

### stepup boot

Source: https://context7.com/reproducible-reporting/stepup-core/llms.txt

Starts the StepUp build process, including the terminal UI, director, and worker processes. It bootstraps the workflow by running plan.py.

```APIDOC
## `stepup boot` — Start the Build

The `stepup boot` command starts the terminal user interface, director, and worker processes, then runs `plan.py` to bootstrap the workflow.

### Usage Examples

```bash
# Single-worker non-interactive run
stepup boot -n 1

# Parallel run with 4 workers
stepup boot -n 4

# Interactive watch mode: press 'r' to re-run after file changes
stepup boot -n 4 -w

# Automatic re-run on file changes
stepup boot -n 4 -W
```

### Related Commands

- `stepup run`: Trigger a new run phase with a running background director.
- `stepup status`: Print workflow status.
- `stepup shutdown`: Graceful shutdown.
- `stepup drain`: Finish current jobs then switch to watch phase.
- `stepup graph`: Dump graph.txt.
```

--------------------------------

### Create Static File Content

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/static_files.md

Example content for a static file named `limerick.txt`.

```text
A coder quite keen,
Whose StepUp skills were unseen,
Wrote limericks with glee,
For all eyes to see,
A truly remarkable scene.
```

--------------------------------

### Example Python Script (plan.py)

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/script_single.md

A Python script that defines the planning phase for StepUp. It returns an empty dictionary, indicating no specific planning actions are required beyond what StepUp handles by default.

```python
from stepup.core.script import driver

def info():
    return {}

def run():
    pass

if __name__ == "__main__":
    driver()

```

--------------------------------

### Explore Graph in Web Browser

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/dependencies.md

Use the `stepup browse` command to start a local web server for interactive graph exploration. Open the provided link in your browser to view the graph. The server reloads the graph on demand.

```bash
stepup browse
```

--------------------------------

### Example Python Script (generate.py)

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/script_single.md

A Python script that utilizes StepUp's driver to perform computations based on a configuration file. It defines `info()` to specify inputs and outputs and `run()` to execute the main logic.

```python
from stepup.core.script import driver
from numpy import cos, sin, save

def info():
    return {
        "inp": ["config.json"],
        "out": ["cos.npy", "sin.npy"],
    }

def run(inp, out):
    with open(inp[0]) as f:
        config = json.load(f)

    nstep = config["nstep"]
    freq = config["freq"]

    x = linspace(0, nstep / freq, nstep)
    save(out[0], cos(x))
    save(out[1], sin(x))

if __name__ == "__main__":
    driver()

```

--------------------------------

### Example of Cyclic Dependency in plan.py

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/cyclic_dependencies.md

This Python script demonstrates how to create a cyclic dependency in StepUp's plan.py. Executing this plan will result in an error.

```python
from stepup.api import plan

@plan.task
def task_a(task_b):
    return 'a'

@plan.task
def task_b(task_a):
    return 'b'

```

--------------------------------

### StepUp Plan for Named Glob Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/static_named_glob.md

The Python script that defines the StepUp build plan. It utilizes named globs to select source files and demonstrates how matched substrings are accessible as attributes on the NGlobMatch object.

```python
{% include 'advanced_topics/static_named_glob/plan.py' %}
```

--------------------------------

### Python Plan for Deferred Glob Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/static_deferred_glob.md

This Python script defines a plan that utilizes a deferred glob pattern. It's used to demonstrate how StepUp Core handles large numbers of files by only making them static when they are required.

```python
from stepup.steps import glob, copy

def plan(plan):
    plan.step(glob('*.txt', _defer=True), name='dg')
    plan.step(copy('foo.txt', 'out.txt'), deps=['dg'])

```

--------------------------------

### Install Asciinema using DNF

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/asciinema/README.md

Install Asciinema using the DNF package manager. This command is specific to Fedora-based systems.

```bash
sudo dnf install asciinema
```

--------------------------------

### Record StepUp interactive tutorial

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/asciinema/README.md

Execute the interactive-runall.sh script to record a demonstration of the interactive use of StepUp. Set the thumbnail frame to 10 seconds.

```bash
./interactive-runall.sh
```

--------------------------------

### Execute StepUp Plan and Verify Output

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/workdir.md

Make your plan script executable, create an output directory, and then run the StepUp boot command to execute the plan. This demonstrates the basic workflow for running a StepUp project.

```bash
chmod +x plan.py
mkdir out/
stepup boot -n 1
```

--------------------------------

### Serve MkDocs Documentation Locally

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/development.md

Run this command to build and serve the documentation locally with live preview. Keep this process running while editing Markdown files.

```bash
mkdocs serve
```

--------------------------------

### Start StepUp in Watch Mode

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/interactive_usage.md

Use this command to start StepUp and keep the terminal user interface running, waiting for file changes. This is useful for interactive development.

```bash
stepup boot -w
```

--------------------------------

### Record StepUp template repository

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/asciinema/README.md

Execute the template-runall.sh script to create a recording of the StepUp template repository. Set the thumbnail frame to 5 seconds.

```bash
./template-runall.sh
```

--------------------------------

### Jinja Template Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/render_jinja.md

A Jinja template file that includes another template and expects variables to be rendered into it.

```jinja
{% include 'advanced_topics/render_jinja/plan.py' %}
```

--------------------------------

### Using StepInfo to Access and Copy Files

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/step_info.md

Demonstrates how to use the StepInfo object to access output files and copy them to a different location. It also shows how to iterate through all input paths.

```python
from stepup.core.api import static, copy
from stepup.fancy.api import create_fancy_pdf  # hypothetical API function

# Plan the creation of the fancy PDF
static("source/")
glob("source/**", _defer=True)
info = create_fancy_pdf("source/")

# Copy files related to the fancy PDF, e.g. to publish them or back up files.
mkdir("../public")
copy(info.filter_out("*.pdf").single, "../public/")
mkdir("../backup")
for path_inp in info.inp:
    copy(path_inp, "../backup")
```

--------------------------------

### Plan File Copy and Directory Creation with StepUp

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/copy_mkdir.md

Use `copy()` and `mkdir()` to define file operations. Ensure directories end with a trailing delimiter for clarity.

```python
from stepup.api import copy, mkdir

# Create a directory named 'sub/'
mkdir('sub/')

# Copy a file into the 'sub/' directory
copy('hello.txt', 'sub/hello.txt')
```

--------------------------------

### Analyze Yappi Profiling Data with SnakeViz

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/development.md

Install SnakeViz and use it to visualize the profiling data generated by Yappi.

```bash
pip install snakeviz
snakeviz .stepup/director.prof
```

--------------------------------

### Email Template File

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/render_jinja.md

An example of an email template file using Jinja syntax, which includes another Jinja snippet.

```jinja
{% include 'advanced_topics/render_jinja/email_include.txt' %}
```

--------------------------------

### Configure Tool Entry Point

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/extending/tool.md

Register your custom tool with the StepUp CLI by defining an entry point in `pyproject.toml`. Replace `your.package` with the actual module path.

```toml
[project.entry-points."stepup.tools"]
custom = "your.package:custom_subcommand"
```

--------------------------------

### Initial Execution Output

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/static_glob_conditional.md

The expected output when `stepup boot -n 1` is run with the `dataset/` directory present. It shows the execution of tasks related to calculating and displaying the average.

```text
booting...
running task_average
running task_cat_average
Average: 3.0

```

--------------------------------

### Set STEPUP_ROOT with direnv

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/reference/environment_variables.md

Example of setting the STEPUP_ROOT environment variable using direnv in a .envrc file. This variable specifies the root directory for StepUp projects.

```bash
export STEPUP_ROOT=${PWD}
```

--------------------------------

### StepUp Workflow Output (First Run)

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/first_step.md

Observe the output generated by StepUp during the initial execution. This includes startup sequences, step execution details, and any output from the steps.

```text
Starting StepUp director...
Using StepUp graph database at .stepup/graph.db
Starting StepUp worker...
Worker started with PID 12345

Step: ./plan.py
START
SUCCESS

Step: runsh echo Hello World
START
SUCCESS

Output for step 'runsh echo Hello World':
Hello World

Cleaning up...
Exiting.

```

--------------------------------

### Python Script using `driver()`

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/call.md

An example of a Python script that uses the `driver()` function to adhere to the call protocol. The `driver()` function handles command-line argument parsing and output management.

```python
from stepup.core.call import driver

def run(parameter):
    return {"result": f"Received parameter: {parameter}"}

if __name__ == "__main__":
    driver()

```

--------------------------------

### Make Plans Executable

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/distributed_plans.md

Grant execute permissions to all plan.py files to allow StepUp to run them.

```bash
chmod +x plan.py sub/plan.py
```

--------------------------------

### Define Build Steps with Dependencies in Python

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/dependencies.md

Use this Python script to define sequential build steps where the output of one step serves as input for the next. This allows StepUp to optimize execution order.

```python
from stepup.api import runsh

def plan():
    runsh('grep', '${inp}/input.txt', '${out}/story.txt')
    runsh('echo', 'Hello world!', '${out}/story.txt')

```

--------------------------------

### Named Glob Pattern Example

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/static_named_glob.md

This pattern matches files where the placeholder '_*name_' contains identical strings on both sides of 'something'. It demonstrates the core concept of named globs for enforcing symmetry in filenames.

```text
prefix_${*name}_something_${*name}.txt
```

--------------------------------

### Making scripts executable and running StepUp

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/getting_started/call.md

Commands to make Python scripts executable and then run the StepUp boot process.

```bash
chmod +x wavegen.py plan.py
stepup boot -n 1
```

--------------------------------

### Expected output from StepUp execution

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/pools.md

This text output shows the expected result of running the plan.py script with StepUp. It illustrates that the 'limited_step' respects the pool size of 2, starting only after other parallel steps have progressed.

```text
booting...
running step 'parallel_step_1'
running step 'parallel_step_2'
running step 'limited_step'
running step 'parallel_step_3'

step 'parallel_step_1' done
step 'parallel_step_2' done
step 'limited_step' done
step 'parallel_step_3' done

all steps done
```

--------------------------------

### Execute plan.py with StepUp

Source: https://github.com/reproducible-reporting/stepup-core/blob/main/docs/advanced_topics/pools.md

This bash command executes the plan.py script using StepUp's boot command with 4 workers. It demonstrates how to run the plan and observe the parallel execution behavior limited by the defined pool.

```bash
chmod +x plan.py
stepup boot -n 4
```