docs and tasks

2026-01-24 13:44:20 +01:00
commit 3ca9c10678
16 changed files with 6704 additions and 0 deletions
--- a/tasks/01-project-setup.md
+++ b/tasks/01-project-setup.md
@@ -0,0 +1,216 @@
+# Task 01: Project Setup
+
+**Phase**: 1 - Core (MVP)
+**Priority**: Critical
+**Estimated Time**: 30 minutes
+**Dependencies**: None
+
+## Objective
+
+Set up the project structure with proper Emacs Lisp package conventions, including file headers, licensing, and build tooling.
+
+## Prerequisites
+
+- Emacs 27.1+ installed
+- Elixir installed and in PATH
+- Git repository initialized
+
+## Steps
+
+### Step 1: Create the main package file
+
+Create `ob-elixir.el` with proper headers:
+
+```elisp
+;;; ob-elixir.el --- Org Babel functions for Elixir -*- lexical-binding: t; -*-
+
+;; Copyright (C) 2024 Your Name
+
+;; Author: Your Name <your.email@example.com>
+;; URL: https://github.com/username/ob-elixir
+;; Keywords: literate programming, reproducible research, elixir
+;; Version: 0.1.0
+;; Package-Requires: ((emacs "27.1") (org "9.4"))
+
+;; This file is not part of GNU Emacs.
+
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation, either version 3 of the License, or
+;; (at your option) any later version.
+
+;;; Commentary:
+
+;; Org Babel support for evaluating Elixir code blocks.
+;;
+;; Features:
+;; - Execute Elixir code in org-mode source blocks
+;; - Support for :results value and :results output
+;; - Variable passing with :var header argument
+;; - Mix project context support
+;;
+;; Usage:
+;; Add (elixir . t) to `org-babel-load-languages':
+;;
+;;   (org-babel-do-load-languages
+;;    'org-babel-load-languages
+;;    '((elixir . t)))
+
+;;; Code:
+
+(require 'ob)
+(require 'ob-eval)
+
+(provide 'ob-elixir)
+;;; ob-elixir.el ends here
+```
+
+### Step 2: Create the Eldev file for build tooling
+
+Create `Eldev` file:
+
+```elisp
+; -*- mode: emacs-lisp; lexical-binding: t; -*-
+
+(eldev-use-package-archive 'gnu)
+(eldev-use-package-archive 'melpa)
+
+;; Test dependencies
+(eldev-add-extra-dependencies 'test 'ert)
+
+;; Use ERT for testing
+(setf eldev-test-framework 'ert)
+
+;; Lint configuration
+(setf eldev-lint-default '(elisp package))
+```
+
+### Step 3: Create test directory structure
+
+```bash
+mkdir -p test
+```
+
+Create `test/test-ob-elixir.el`:
+
+```elisp
+;;; test-ob-elixir.el --- Tests for ob-elixir -*- lexical-binding: t; -*-
+
+;;; Commentary:
+
+;; Test suite for ob-elixir package.
+
+;;; Code:
+
+(require 'ert)
+
+;; Add parent directory to load path
+(let ((dir (file-name-directory (or load-file-name buffer-file-name))))
+  (add-to-list 'load-path (expand-file-name ".." dir)))
+
+(require 'ob-elixir)
+
+(ert-deftest ob-elixir-test-package-loads ()
+  "Test that the package loads successfully."
+  (should (featurep 'ob-elixir)))
+
+(provide 'test-ob-elixir)
+;;; test-ob-elixir.el ends here
+```
+
+### Step 4: Create Makefile
+
+Create `Makefile`:
+
+```makefile
+EMACS ?= emacs
+BATCH = $(EMACS) -Q -batch -L .
+
+.PHONY: all compile test lint clean
+
+all: compile test
+
+compile:
+	$(BATCH) -f batch-byte-compile ob-elixir.el
+
+test:
+	$(BATCH) -l ert -l test/test-ob-elixir.el \
+		-f ert-run-tests-batch-and-exit
+
+lint:
+	$(BATCH) --eval "(require 'package)" \
+		--eval "(package-initialize)" \
+		--eval "(package-refresh-contents)" \
+		--eval "(package-install 'package-lint)" \
+		-l package-lint \
+		-f package-lint-batch-and-exit ob-elixir.el
+
+clean:
+	rm -f *.elc test/*.elc
+```
+
+### Step 5: Create .gitignore
+
+Create `.gitignore`:
+
+```
+# Byte-compiled files
+*.elc
+
+# Eldev
+.eldev/
+Eldev-local
+
+# Package archives
+/packages/
+
+# Test artifacts
+/test/tmp/
+
+# Editor
+*~
+\#*\#
+.#*
+
+# OS
+.DS_Store
+```
+
+### Step 6: Verify setup
+
+Run the following commands to verify:
+
+```bash
+# Check Emacs version
+emacs --version
+
+# Check Elixir version
+elixir --version
+
+# Run tests
+make test
+
+# Compile
+make compile
+```
+
+## Acceptance Criteria
+
+- [ ] `ob-elixir.el` exists with proper headers
+- [ ] Package loads without errors: `(require 'ob-elixir)`
+- [ ] `make test` runs successfully
+- [ ] `make compile` produces no warnings
+- [ ] All files follow Emacs Lisp conventions
+
+## Files Created
+
+- `ob-elixir.el` - Main package file
+- `Eldev` - Build tool configuration
+- `Makefile` - Make targets
+- `test/test-ob-elixir.el` - Test file
+- `.gitignore` - Git ignore rules
+
+## References
+
+- [docs/01-emacs-elisp-best-practices.md](../docs/01-emacs-elisp-best-practices.md)
+- [docs/02-testing-emacs-elisp.md](../docs/02-testing-emacs-elisp.md)