From eaa87edb3866609b1c0c7ac672ae5facc87b7915 Mon Sep 17 00:00:00 2001
From: "carpentry-heartbeat[bot]"
 <carpentry-heartbeat[bot]@users.noreply.github.com>
Date: Thu, 21 May 2026 05:11:39 +0200
Subject: [PATCH] Update template to modern Carp idioms

Add module-level doc to MyMod, add docs-url config to gendocs.carp,
and clarify in README that the main file should be renamed to match
the module name.
---
 README.md    | 11 +++++++----
 gendocs.carp |  1 +
 main.carp    | 24 ++++++++++++++++++------
 3 files changed, 26 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index 59ef274..1d27b59 100644
--- a/README.md
+++ b/README.md
@@ -5,9 +5,11 @@ You should be able to reuse its structure for your projects!
 
 ## Overview
 
-This template comes with a simple entrypoint called `main.carp`. This is the
-file that people will load when they first load your project. It doesn’t
-currently compile—can you find out why?
+This template comes with a simple entrypoint called `main.carp`. **Rename this
+file to match your module name** (e.g. `my-mod.carp` for a module called
+`MyMod`). This is the convention used by carpentry-org packages and makes your
+library easier to discover. Remember to update the `(load ...)` paths in
+`gendocs.carp` and `test/tests.carp` when you rename it.
 
 We also have some tests. They reside in `test/tests.carp`. If we run them using
 `carp -x test/tests.carp`, they fail! Please write some useful tests for your
@@ -18,7 +20,8 @@ invoke it by calling `carp gendocs.carp`) will generate documentation from the
 docstrings of your functions and modules, and put it in the `docs/` directory.
 You can style and customize it by editing the CSS or fiddling with the
 configuration options in `gendocs.carp`. They should be pretty
-self-explanatory.
+self-explanatory. Make sure to update `docs-url` in `gendocs.carp` to point to
+your repository.
 
 <hr/>
 
diff --git a/gendocs.carp b/gendocs.carp
index 1be3762..ddab9cb 100644
--- a/gendocs.carp
+++ b/gendocs.carp
@@ -3,6 +3,7 @@
 (Project.config "title" "My Awesome Project")
 (Project.config "docs-directory" "./docs/")
 (Project.config "docs-logo" "")
+(Project.config "docs-url" "https://github.com/your-user/your-project")
 (Project.config "docs-styling" "style.css")
 
 ; useful if you only have 1 module
diff --git a/main.carp b/main.carp
index fb54c3b..4d99739 100644
--- a/main.carp
+++ b/main.carp
@@ -1,10 +1,22 @@
+(doc MyMod "is a template module you should replace with your own.
+
+## Installation
+
+```
+(load \"git@github.com:your-user/your-project@0.1.0\")
+```
+
+## Usage
+
+```
+(MyMod.greet \"Carp\") ; => \"Hello, Carp!\"
+```
+
+Rename this file to match your module name (e.g. `my-mod.carp` for a
+module called `MyMod`). See the carpentry-org packages for examples.")
 (defmodule MyMod
   (doc greet "returns a friendly greeting for `name`.")
-  (defn greet [name]
-    (if (= name "Carp")
-      @"Hello, Carp!"
-      @"Hello!"))
+  (defn greet [name] (if (= name "Carp") @"Hello, Carp!" @"Hello!"))
 
   (doc myfun "is a tiny no-op function used by tests.")
-  (defn myfun [] ())
-)
+  (defn myfun [] ()))