chore(docs): update README and dependencies for improved setup

jonaprieto · jonaprieto · commit d7ea640d3fd8 · 2025-04-30T00:39:02.000-05:00
The README.md has been significantly expanded to include a more detailed setup guide, installation instructions, and common commands. Key tools such as 'uv', 'graphviz', 'juvix', and 'just' are emphasized for local development. Furthermore, the VERSION file is updated from v0.1.4 to v0.2.0, reflecting substantial changes.

The setup configuration in justfile has been adjusted by removing unnecessary assertions for 'just' installation. Additionally, redundant dependencies related to 'just' have been removed from pyproject.toml, requirements.txt, and related lock files, simplifying the dependency management and cleanup of unnecessary packages. This change leads to a cleaner setup process and reduces potential conflicts.
diff --git a/README.md b/README.md
@@ -4,45 +4,136 @@
 
 ## Getting Started
 
-- **Contribute**: [Tutorial](https://specs.anoma.net/latest/tutorial/index.html)
-- **Markdown**: Uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/)
+Welcome to the Anoma Specs repository! This project uses [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/reference/) for documentation and is designed for easy contribution and local development.
 
-### Setup
+- **Latest Specs**: [https://specs.anoma.net/latest/](https://specs.anoma.net/latest/)
 
-1. **Prerequisites**:
+---
 
-   - `uv`: Install via:
+## Quick Start
 
-     ```bash
-     # macOS/Linux
-     curl -LsSf https://astral.sh/uv/install.sh | sh
-     # Windows
-     powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
-     ```
-   - `graphviz` for local deployment,
+### 1. Prerequisites
 
-   - `juvix` for local deployment,
-
-     ```bash
-     curl --proto '=https' --tlsv1.2 -sSfL https://get.juvix.org | sh
-     ```
-   - `just` for local development (although you can use `uv run` for most commands)
-
-2. **Setup Commands**:
+Make sure you have the following tools installed:
 
+- **uv** (Python package/dependency manager)
+  - macOS/Linux:
     ```bash
-    just setup-repo
+    curl -LsSf https://astral.sh/uv/install.sh | sh
     ```
+  - Windows:
+    ```powershell
+    powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+    ```
+  - Or via Homebrew:
+    ```bash
+    brew install uv
+    ```
+
+- **graphviz** (for local documentation deployment)
+
+- **juvix** (for typechecking and specs development)
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSfL https://get.juvix.org | sh
+  ```
+
+- **just** (a simple command runner, replacement for Make)
+  - Install via your [package manager](https://github.com/casey/just?tab=readme-ov-file#cross-platform).
+
+---
+
+### 2. Installation
+
+Choose one of the following:
+
+- With **uv**:
+  ```bash
+  uv sync
+  ```
+- With **just**:
+  ```bash
+  just sync
+  ```
+- With **pip**:
+  ```bash
+  pip install -r requirements.txt
+  ```
+
+---
+
+### 3. Common Commands
+
+You can use either `just` or `uv run` for most tasks. Below are the most common commands:
+
+#### Dependency Management
+
+| Task                        | Command                                        | Command (just)      |
+|-----------------------------|------------------------------------------------|---------------------|
+| Synchronize dependencies    | `uv sync`                                      | `just sync`         |
+| Run all pre-commit checks   | `uv run pre-commit -- run --all-files`         | `just check`        |
+| Typecheck the code          | `juvix typecheck docs/everything.juvix.md`     | `just juvix-check`  |
+
+#### Development Tools
+
+- **Install pre-commit hooks** (for specs writers only):
+  ```bash
+  uv run pre-commit -- install --install-hooks
+  ```
+  or
+  ```bash
+  just install-hooks
+  ```
+
+- **Install development tools**:
+  ```bash
+  uv tool install pre-commit
+  uv tool install commitizen
+  ```
+  or
+  ```bash
+  just install-tools
+  ```
+
+#### Documentation
+
+| Task                        | Command                                        | Command (just)      |
+|-----------------------------|------------------------------------------------|---------------------|
+| Build documentation         | `uv run mkdocs build --config-file mkdocs.yml` | `just build`        |
+| Serve documentation locally | `uv run mkdocs serve --config-file mkdocs.yml` | `just serve`        |
+
+#### Git Operations
+
+| Task                        | Command                                        | Command (just)      |
+|-----------------------------|------------------------------------------------|---------------------|
+| Commit using commitizen     | `uv run cz commit`                             | `just commit`       |
+| Commit skipping hooks       | `git commit --no-verify -m "<msg>"`            | `just commit-skip`  |
+| Amend commit (skip hooks)   | `git commit --amend --no-verify`               | `just commit-amend` |
+| Amend using commitizen      | `uv run cz commit --amend`                     | `just cz-amend`     |
+
+If you have installed the pre-commit hooks (which is recommended), but need to
+make a commit or push changes without running the hooks (for example, when
+working on a branch or PR), you can use the `--no-verify` flag as shown in the
+table above. The Commitizen is a tool to help you write better commit messages.
+
+---
+
+### 4. Short Reference
+
+- **Install**: `uv sync` or `pip install -r requirements.txt`
+- **Build**: `just build` or `uv run mkdocs build`
+- **Serve Locally**: `just serve` or `uv run mkdocs serve`
 
-### Documentation
+---
 
-- **Build**: `just build`
-- **Serve Locally**: `just serve`
+## Development with Nix
 
-### Development with Nix
+If you use [Nix](https://nixos.org/download/):
 
 1. **Install Nix**: [Download](https://nixos.org/download/)
 2. **Enable Flakes**: [Guide](https://nixos.wiki/wiki/flakes)
-3. **Enter Shell**: `nix develop`
+3. **Enter Development Shell**:
+   ```bash
+   nix develop
+   ```
 
 <!-- --8<-- [end:all]-- -->
diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-v0.1.4
+v0.2.0
diff --git a/justfile b/justfile
@@ -3,7 +3,6 @@
 # Set up the repository with all dependencies and hooks
 setup-repo:
 	uv sync
-	uv tool install just || true
 	just install-hooks
 	just install-tools
 
@@ -29,7 +28,7 @@ lock:
 
 # Export dependencies
 export:
-	uv export
+	uv export --frozen --output-file=requirements.txt
 
 # Run all pre-commit checks
 check:
@@ -64,9 +63,9 @@ commit-skip m:
 	git commit --no-verify -m "{{m}}"
 
 # Amend skipping pre-commit hooks
-amend:
+commit-amend:
 	git commit --amend --no-verify
 
 # Amend using commitizen
-amend-cz:
+cz-amend:
 	uv run cz commit --amend
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -3,7 +3,7 @@ site_author: !ENV [SITE_AUTHOR, "Anoma Foundation"]
 site_description: !ENV [SITE_DESCRIPTION, "The Anoma specs is a collection of documents that describe the architecture, design, and implementation of the Anoma Network."]
 site_dir: !ENV [SITE_DIR, site]
 site_url: !ENV [SITE_URL, 'https://specs.anoma.net/latest/']
-site_version: !ENV [SITE_VERSION, "v0.1.4"]
+site_version: !ENV [SITE_VERSION, "v0.2.0"]
 copyright: !ENV [COPYRIGHT, "&copy; 2025 <a href=\"https://anoma.net\">Anoma Foundation</a>"]
 repo_url: https://github.com/anoma/nspec
 repo_name: anoma/nspec
diff --git a/pyproject.toml b/pyproject.toml
@@ -5,7 +5,6 @@ description = "NSpec is a specification project for the Anoma network."
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
-    "just>=0.8.162",
     "mdx-truly-sane-lists>=1.3",
     "mkdocs>=1.6.1",
     "mkdocs-bibtex>=4.2.5",
diff --git a/requirements.txt b/requirements.txt
@@ -83,9 +83,6 @@ charset-normalizer==3.4.1 \
     # via
     #   commitizen
     #   requests
-ciso8601==2.3.2 \
-    --hash=sha256:ec1616969aa46c51310b196022e5d3926f8d3fa52b80ec17f6b4133623bd5434
-    # via just
 click==8.1.8 \
     --hash=sha256:63c132bbbed01578a06712a2d1f497bb62d9c1c0d329b7903a866228027263b2 \
     --hash=sha256:ed53c9d8990d83c2a27deae68e4ee337473f6330c040a31d4225c9574d16096a
@@ -134,9 +131,6 @@ ghp-import==2.1.0 \
     --hash=sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619 \
     --hash=sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343
     # via mkdocs
-glob2==0.7 \
-    --hash=sha256:85c3dbd07c8aa26d63d7aacee34fa86e9a91a3873bc30bf62ec46e531f92ab8c
-    # via just
 graphviz==0.20.3 \
     --hash=sha256:09d6bc81e6a9fa392e7ba52135a9d49f1ed62526f96499325930e87ca1b5925d \
     --hash=sha256:81f848f2904515d8cd359cc611faba817598d2feaac4027b266aa3eda7b3dde5
@@ -168,10 +162,6 @@ jinja2==3.1.6 \
     #   mkdocs
     #   mkdocs-macros-plugin
     #   mkdocs-material
-just==0.8.162 \
-    --hash=sha256:9804e695b3a7d5284314fb19cc9c1216a52da01dd0aa802c264d95984ca84485 \
-    --hash=sha256:e96951a90601f15e105a45348ecf472e2618ee38e16e1fa6f149017b2a32f773
-    # via nspec
 latexcodec==3.0.0 \
     --hash=sha256:6f3477ad5e61a0a99bd31a6a370c34e88733a6bad9c921a3ffcfacada12f41a7 \
     --hash=sha256:917dc5fe242762cc19d963e6548b42d63a118028cdd3361d62397e3b638b6bc5
@@ -213,9 +203,7 @@ lxml==5.4.0 \
     --hash=sha256:d12832e1dbea4be280b22fd0ea7c9b87f0d8fc51ba06e92dc62d52f804f78ebd \
     --hash=sha256:d5663bc1b471c79f5c833cffbc9b87d7bf13f87e055a5c86c363ccd2348d7e82 \
     --hash=sha256:e794f698ae4c5084414efea0f5cc9f4ac562ec02d66e1484ff822ef97c2cadff
-    # via
-    #   just
-    #   mkdocs-drawio
+    # via mkdocs-drawio
 markdown==3.8 \
     --hash=sha256:794a929b79c5af141ef5ab0f2f642d0f7b1872981250230e72682346f7cc90dc \
     --hash=sha256:7df81e63f0df5c4b24b7d156eb81e4690595239b7d70937d0409f1b0de319c6f
@@ -346,23 +334,6 @@ numpy==2.2.5 \
     --hash=sha256:d8882a829fd779f0f43998e931c466802a77ca1ee0fe25a3abe50278616b1471 \
     --hash=sha256:e8b025c351b9f0e8b5436cf28a07fa4ac0204d67b38f01433ac7f9b870fa38c6
     # via ncls
-orjson==3.10.16 \
-    --hash=sha256:148a97f7de811ba14bc6dbc4a433e0341ffd2cc285065199fb5f6a98013744bd \
-    --hash=sha256:15a1431a245d856bd56e4d29ea0023eb4d2c8f71efe914beb3dee8ab3f0cd7fb \
-    --hash=sha256:1d960c1bf0e734ea36d0adc880076de3846aaec45ffad29b78c7f1b7962516b8 \
-    --hash=sha256:28f79944dd006ac540a6465ebd5f8f45dfdf0948ff998eac7a908275b4c1add6 \
-    --hash=sha256:6fd5da4edf98a400946cd3a195680de56f1e7575109b9acb9493331047157430 \
-    --hash=sha256:980ecc7a53e567169282a5e0ff078393bac78320d44238da4e246d71a4e0e8f5 \
-    --hash=sha256:a318cd184d1269f68634464b12871386808dc8b7c27de8565234d25975a7a137 \
-    --hash=sha256:b94dda8dd6d1378f1037d7f3f6b21db769ef911c4567cbaa962bb6dc5021cf90 \
-    --hash=sha256:c83655cfc247f399a222567d146524674a7b217af7ef8289c0ff53cfe8db09f0 \
-    --hash=sha256:ca5426e5aacc2e9507d341bc169d8af9c3cbe88f4cd4c1cf2f87e8564730eb56 \
-    --hash=sha256:d2aaa5c495e11d17b9b93205f5fa196737ee3202f000aaebf028dc9a73750f10 \
-    --hash=sha256:df23f8df3ef9223d1d6748bea63fca55aae7da30a875700809c500a05975522b \
-    --hash=sha256:f12970a26666a8775346003fd94347d03ccb98ab8aa063036818381acf5f523e \
-    --hash=sha256:fa59ae64cb6ddde8f09bdbf7baf933c4cd05734ad84dcf4e43b887eb24e37652 \
-    --hash=sha256:fe0a145e96d51971407cb8ba947e63ead2aa915db59d6631a355f5f2150b56b7
-    # via just
 outcome==1.3.0.post0 \
     --hash=sha256:9dcf02e65f2971b80047b377468e72a268e15c0af3cf1238e6ff14f7f91143b8 \
     --hash=sha256:e771c5ce06d1415e356078d3bdd68523f284b4ce5419828922b6871e65eda82b
@@ -464,7 +435,6 @@ pyyaml==6.0.2 \
     --hash=sha256:efdca5630322a10774e8e98e1af481aad470dd62c3170801852d752aa7a783ba
     # via
     #   commitizen
-    #   just
     #   mkdocs
     #   mkdocs-get-deps
     #   mkdocs-macros-plugin
@@ -505,16 +475,10 @@ requests==2.32.3 \
     --hash=sha256:55365417734eb18255590a9ff9eb97e9e1da868d4ccd6402399eaf68af20a760 \
     --hash=sha256:70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6
     # via
-    #   just
     #   mkdocs-bibtex
     #   mkdocs-kroki-plugin
     #   mkdocs-material
-    #   requests-viewer
     #   responses
-requests-viewer==0.0.12 \
-    --hash=sha256:1cee8d41963d43add1f44315cd173fe41a6de1b4e13ba5176379e887d713bc30 \
-    --hash=sha256:d7ef4c13f03fcabbb118512b94007af7b8723089c19ab90542c8bfc0c3fb771f
-    # via just
 responses==0.25.7 \
     --hash=sha256:8ebae11405d7a5df79ab6fd54277f6f2bc29b2d002d0dd2d5c632594d1ddcedb \
     --hash=sha256:92ca17416c90fe6b35921f52179bff29332076bb32694c0df02dcac2c6bc043c
diff --git a/uv.lock b/uv.lock
