Merge pull request #50 from akhundMurad/feat/core/37

Add full docs site and enhance CLI/docstrings

Author: akhundMurad

.github/workflows/ci.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.11"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v3
@@ -37,7 +37,7 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.11"
 
       - name: Install uv
         uses: astral-sh/setup-uv@v3
@@ -49,3 +49,7 @@ jobs:
       - name: Run tests
         run: |
           make test
+      
+      - name: Run doc tests
+        run: |
+          make test-docs

.github/workflows/docs.yml

@@ -0,0 +1,28 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mkdocstrings[python] mkdocs-git-revision-date-localized-plugin
+          pip install -e .
+
+      - name: Deploy
+        run: mkdocs gh-deploy --force

CONTRIBUTING.md

@@ -18,7 +18,7 @@ Thank you for taking the time to contribute ❤️
 2. Clone your fork locally:
 
 ```bash
-git clone https://github.com/<your-username>/typeid-python.git
+git clone https://github.com/akhundMurad/typeid-python.git
 cd typeid-python
 ```
 

Makefile

@@ -38,3 +38,16 @@ release:
 
 test:
 	uv run pytest -v
+
+
+test-docs:
+	uv run pytest README.md docs/ --markdown-docs
+
+
+docs:
+	mkdocs serve
+
+
+docs-build: 
+	mkdocs build
+

README.md

@@ -64,25 +64,30 @@ If the extra is not installed, JSON schemas will still work.
     ```python
     from typeid import TypeID
 
+    # Default TypeID (no prefix)
     typeid = TypeID()
 
-    print(typeid.prefix)  # ""
-    print(typeid.suffix)  # "01h45ytscbebyvny4gc8cr8ma2" (encoded uuid7 instance)
+    assert typeid.prefix == ""
+    assert isinstance(typeid.suffix, str)
+    assert len(typeid.suffix) > 0  # encoded UUIDv7
 
+    # TypeID with prefix
     typeid = TypeID(prefix="user")
 
-    print(typeid.prefix)  # "user"
-    print(str(typeid))  # "user_01h45ytscbebyvny4gc8cr8ma2"
+    assert typeid.prefix == "user"
+    assert str(typeid).startswith("user_")
     ```
 
 - Create TypeID from string:
 
     ```python
     from typeid import TypeID
 
-    typeid = TypeID.from_string("user_01h45ytscbebyvny4gc8cr8ma2")
+    value = "user_01h45ytscbebyvny4gc8cr8ma2"
+    typeid = TypeID.from_string(value)
 
-    print(str(typeid))  # "user_01h45ytscbebyvny4gc8cr8ma2"
+    assert str(typeid) == value
+    assert typeid.prefix == "user"
     ```
 
 - Create TypeID from uuid7:
@@ -91,12 +96,37 @@ If the extra is not installed, JSON schemas will still work.
     from typeid import TypeID
     from uuid6 import uuid7
 
-    uuid = uuid7()  # UUID('01890bf0-846f-7762-8605-5a3abb40e0e5')
+    uuid = uuid7()
     prefix = "user"
 
     typeid = TypeID.from_uuid(prefix=prefix, suffix=uuid)
 
-    print(str(typeid))  # "user_01h45z113fexh8c1at7axm1r75"
+    assert typeid.prefix == prefix
+    assert str(typeid).startswith(f"{prefix}_")
+
+    ```
+
+- Use pre-defined prefix:
+
+    ```python
+    from dataclasses import dataclass, field
+    from typing import Literal
+    from typeid import TypeID, typeid_factory
+
+    UserID = TypeID[Literal["user"]]
+    gen_user_id = typeid_factory("user")
+
+
+    @dataclass
+    class UserDTO:
+        user_id: UserID = field(default_factory=gen_user_id)
+        full_name: str = "A J"
+        age: int = 18
+
+
+    user = UserDTO()
+
+    assert str(user.user_id).startswith("user_")
     ```
 
 ### CLI-tool

docs/concepts.md

@@ -0,0 +1,116 @@
+# Concepts
+
+TypeID exists because identifiers are used for much more than uniqueness.
+
+They appear in logs, URLs, dashboards, tickets, alerts, database rows, and Slack messages.  
+Yet most identifiers—especially UUIDs—are opaque. They carry no meaning, no context, and no affordances for inspection.
+
+TypeID is an attempt to fix that, without breaking the properties that make UUIDs useful.
+
+---
+
+## TypeID as an identifier
+
+A TypeID is a string identifier composed of two independent parts:
+
+```text
+<prefix>_<suffix>
+```
+
+For example:
+
+```text
+user_01h45ytscbebyvny4gc8cr8ma2
+```
+
+The **suffix** is the identity. It is globally unique and backed by a UUID.
+The **prefix** is context. It tells a human (and tooling) what kind of thing the identifier refers to.
+
+Crucially, the prefix does *not* participate in uniqueness. Two TypeIDs with different prefixes but the same suffix represent the same underlying UUID. The prefix is a semantic layer, not a storage primitive.
+
+This separation is intentional. It allows TypeID to add meaning without interfering with existing UUID-based systems.
+
+## UUID compatibility by design
+
+TypeID is not a replacement for UUIDs. It is a layer on top of them.
+
+Every TypeID corresponds to exactly one UUID, and that UUID can always be extracted or reconstructed. This makes it possible to:
+
+* store native UUIDs in databases
+* use existing UUID indexes and constraints
+* introduce TypeID without schema migrations
+* roll back or interoperate with systems that know nothing about TypeID
+
+The recommended pattern is simple: **store UUIDs, expose TypeIDs**.
+
+TypeID lives at the boundaries of your system—APIs, logs, tooling—not at the lowest storage level.
+
+## Sortability and time
+
+The suffix used by TypeID is time-sortable. When two TypeIDs are compared lexicographically, the one created earlier sorts before the one created later.
+
+This property is not about business semantics; it is about ergonomics.
+
+Sortable identifiers make logs readable, pagination predictable, and debugging less frustrating. When you scan a list of IDs, you can usually infer their relative age without additional metadata.
+
+There are important limits to this property. Ordering reflects **generation time**, not transaction time or business events. Clock skew and distributed systems still exist. TypeID does not attempt to impose global ordering or causality.
+
+Sortability is a convenience, not a guarantee.
+
+## Explainability
+
+Once an identifier carries structure, it becomes possible to inspect it.
+
+TypeID can be *explained*: given a string, the system can determine whether it is a valid TypeID, extract its UUID, derive its creation time, and report these facts in a structured way.
+
+This is useful in places where identifiers normally appear as dead text:
+
+* logs
+* error messages
+* database dumps
+* incident reports
+* CI output
+
+Explainability is designed to be safe. Invalid identifiers do not crash the system. Unknown prefixes are accepted. Each identifier is handled independently, which makes batch processing robust.
+
+## Schemas as optional meaning
+
+Derived facts are always available, but they are not always enough. In real systems, prefixes often correspond to domain concepts: users, orders, events, aggregates.
+
+Schemas allow you to describe that meaning explicitly.
+
+A schema can say that a `user` ID represents an end-user account, that it contains PII, that it is owned by a particular team, or that related logs and dashboards can be found at specific URLs.
+
+Schemas are optional and additive. If a schema is missing, outdated, or invalid, TypeID still works. The identifier does not become invalid because metadata could not be loaded.
+
+This separation keeps the core identifier system stable while allowing richer interpretation where it is useful.
+
+## Unknown and invalid identifiers
+
+TypeID makes a clear distinction between identifiers that are **invalid** and those that are merely **unknown**.
+
+An invalid identifier is structurally wrong: it cannot be parsed or decoded.
+An unknown identifier is structurally valid, but its prefix is not recognized by any schema.
+
+Unknown identifiers are first-class citizens. They allow systems to evolve independently and avoid tight coupling between producers and consumers of IDs.
+
+This distinction is essential for forward compatibility and safe tooling.
+
+## A note on safety
+
+TypeID is deliberately conservative.
+
+It does not infer meaning.
+It does not mutate state.
+It does not enforce authorization.
+It does not treat identifiers as secrets.
+
+Its goal is to make identifiers **more understandable**.
+
+## Closing thoughts
+
+TypeID treats identifiers as part of the system’s interface, not as incidental implementation details.
+
+By combining UUID compatibility, time-based sortability, and structured explainability, it aims to make everyday engineering tasks—debugging, inspection, reasoning—slightly less painful.
+
+Identifiers should not be mysterious. They should be inspectable, understandable, and boring in the best possible way.

docs/contributing.md

@@ -0,0 +1 @@
+--8<-- "CONTRIBUTING.md"