Skip to content

Developer guide

This guide is for developers who want to work on this repository. It covers how to run the documentation site locally and describes the repository-specific tooling used to maintain component templates and generated README files.

Prerequisites

Install the Task runner

macOS

brew install go-task/tap/go-task

Linux

sh -c "$(curl --location https://taskfile.dev/install.sh)" -- -d -b /usr/local/bin

Windows

choco install go-task

Running the documentation site locally

task docs-serve

This command installs dependencies and starts a local server at http://localhost:8000. The site reloads automatically as you edit files in the docs/ directory.

If you only need to review or edit the documentation for this repository, this is the only section you need.

Copier watch

Use this section only if you are developing or testing an App Framework component template. It is not required for ordinary documentation edits in this repository.

tools/copier-watch/copier-watch.py is a development tool for iterating efficiently on copier templates such as af-component-fastapi-backend.

The script watches all file changes in a source template repository. When you edit a template, it:

  1. Creates a local commit on the source repository and amends it on each subsequent change.
  2. Runs copier update on the destination repository using that local commit.

This lets you iterate on Jinja templates without pushing remote commits. For each change in the source repository, it also resets the destination repository and applies the full changeset from scratch, so you do not accumulate partial changes.

Warning

This script modifies Git repositories and can cause data loss. Ensure the destination repository has a clean git status before use. It runs git reset and git clean on the destination.

Copier watch usage

uv run tools/copier-watch/copier-watch.py \
  --commit-message 'Adjusted backend' \
  --answers-file .datarobot/answers/fastapi-web.yml \
  ~/code/af-component-fastapi-backend \
  ~/code/recipe-talk-to-my-docs

Arguments:

Argument Description
--commit-message Message for the local amended commit on the source repository.
--answers-file Path to the copier answers file in the destination repository.
SOURCE_REPOSITORY Path to the component template repository being edited.
DESTINATION_REPOSITORY Path to the recipe repository that receives the changes.

Typical workflow

  • Top terminal: pytest watcher running in the destination repository.
  • Bottom-left terminal: copier-watch watching af-component-fastapi-backend for changes.
  • Bottom-right terminal: template editing. When tests change, the updated template is applied to the destination repository, and pytest-watcher detects the updates automatically.

copier-watch demo

Component doc update

tools/af_component_doc_update generates a README.generated.md scaffold for App Framework component repositories. It reads the component's copier-module.yaml, which declares the module name, description, dependencies, and whether the component is repeatable, and renders a structured README template with standard sections prefilled plus placeholder comments for the parts that need human authoring.

Component doc update usage

From the tools/af_component_doc_update directory:

uv run af-component-doc-update ~/code/af-component-fastapi-backend

This writes README.generated.md into the target component repository. The output includes:

  • Header with badges (version, license) and links.
  • Quick start (dr component add and uvx copier copy commands).
  • Component dependencies table (required and collaborates-with), populated from copier-module.yaml.
  • Section scaffolding with inline authoring guidance for: prerequisites, local development, troubleshooting, next steps, and contributing.

The [[INSERT ... HERE]] placeholders and comment blocks guide what to write in each section. Delete the comments once the section is filled in.