Create online docs

.github/workflows/docs.yml

@@ -0,0 +1,61 @@
+name: Build and Deploy Documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - name: Setup OCaml
+      uses: ocaml/setup-ocaml@v2
+      with:
+        ocaml-compiler: 4.14.x
+        dune-cache: true
+
+    - name: Install dependencies  
+      run: opam install . --deps-only --with-doc
+
+    - name: Build project
+      run: opam exec -- dune build
+
+    - name: Build documentation
+      run: opam exec -- dune build @doc
+
+    - name: Setup Pages
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+      uses: actions/configure-pages@v4
+
+    - name: Upload artifact
+      if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: '_build/default/_doc/_html'
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-22.04
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4 

Makefile

@@ -5,13 +5,13 @@
 
 DUNE 	= dune
 
-.PHONY: all install test clean uninstall format install-ocamlformat
+.PHONY: all install test clean uninstall format install-ocamlformat doc doc-serve
 
 all:
 	$(DUNE) build
 
 install: all
-	$(DUNE) install hello
+	$(DUNE) install stdnum
 
 uninstall:
 	$(DUNE) uninstall
@@ -28,10 +28,17 @@ clean:
 utop:
 	$(DUNE) utop
 
+doc:
+	$(DUNE) build @doc
+
+doc-serve: doc
+	@echo "Starting documentation server at http://localhost:8080"
+	@echo "Press Ctrl+C to stop"
+	cd _build/default/_doc/_html && python3 -m http.server 8080
+
 format:
 	$(DUNE) build --auto-promote @fmt
-	opam lint --normalise hello.opam > hello.tmp && mv hello.tmp hello.opam
-	git ls-files '**/*.[ch]' | xargs -n1 indent -nut -i8
+	opam lint --normalise stdnum.opam > stdnum.tmp && mv stdnum.tmp stdnum.opam
 
 install-ocamlformat:
 	opam install -y ocamlformat=0.26.1

README_DEV.md

@@ -0,0 +1,80 @@
+# Developer Documentation
+
+## Building Documentation
+
+This project uses `odoc` for generating documentation from OCaml interface files.
+
+### Prerequisites
+
+Make sure you have `odoc` installed:
+```bash
+opam install odoc
+```
+
+### Building Documentation
+
+To build the documentation:
+```bash
+make doc
+```
+
+This will generate HTML documentation in `_build/default/_doc/_html/`.
+
+### Serving Documentation Locally
+
+To serve the documentation locally on port 8080:
+```bash
+make doc-serve
+```
+
+This will start a Python HTTP server and open the documentation at http://localhost:8080
+
+**Note:** You need Python 3 installed for the local server. Press Ctrl+C to stop the server.
+
+### Documentation Guidelines
+
+When writing documentation in `.mli` files:
+
+1. **Module-level documentation**: Use `(** {1 Title} ... *)` at the top
+2. **Function documentation**: Use `(** ... *)` before each function
+3. **Parameters**: Use `@param name description`
+4. **Return values**: Use `@return description`  
+5. **Exceptions**: Use `@raise Exception description`
+6. **Examples**: Use code blocks with `{[ ... ]}`
+
+#### Example:
+```ocaml
+(** {1 Number Validation}
+
+    This module validates identification numbers.
+*)
+
+(** [validate number] validates the given number.
+
+    @param number The number to validate
+    @return The cleaned and validated number
+    @raise Invalid_format if the number is invalid
+
+    {[validate "123-45-6789" = "123456789"]} *)
+val validate : string -> string
+```
+
+### Documentation Structure
+
+- `/` - Main library documentation
+- `/stdnum/` - Main module
+- `/stdnum/Stdnum/` - Core library documentation
+- `/stdnum/Tools/` - Utility functions
+- `/stdnum/Us/` - US numbers (when implemented)
+- `/stdnum/Pl/` - Polish numbers (when implemented)
+
+### Deployment
+
+Documentation is automatically deployed to GitHub Pages when pushed to main branch via GitHub Actions.
+
+## Development Workflow
+
+1. Write/update `.mli` files with proper documentation
+2. Run `make doc` to build locally
+3. Run `make doc-serve` to preview at http://localhost:8080
+4. Commit and push - documentation will be auto-deployed 

dune-project

@@ -13,15 +13,20 @@
 )
 (license LICENSE)
 
-(documentation https://url/to/documentation)
+(documentation https://kupolak.github.io/stdnum/)
 
 (package
  (name stdnum)
- (synopsis "Ocaml library to provide functions to handle, parse and validate standard numbers.")
+ (synopsis "OCaml library to provide functions to handle, parse and validate standard numbers.")
  (description "The stdnum library in OCaml provides functions for handling, parsing,
-  and validating standard numbers. It can be used for identifiers like PESEL, NIP, REGON.")
- (depends ocaml dune alcotest)
+  and validating standard numbers. It can be used for identifiers like PESEL, NIP, REGON,
+  SSN, ITIN, EIN, ATIN and many others from various countries.")
+ (depends 
+  ocaml 
+  dune 
+  alcotest
+  (odoc :with-doc))
  (tags
-  (validation, identity-card-validation standards utils check checker)))
+  (validation identity-card-validation standards utils check checker)))
 
 ; See the complete stanza docs at https://dune.readthedocs.io/en/stable/dune-files.html#dune-project

lib/ad/dune

@@ -1,4 +1,5 @@
 (library
  (name ad)
+ (public_name stdnum.ad)
  (modules nrt)
  (libraries tools))

lib/al/dune

@@ -1,4 +1,5 @@
 (library
  (name al)
+ (public_name stdnum.al)
  (modules nipt)
  (libraries tools))

lib/ar/dune

@@ -1,4 +1,5 @@
 (library
  (name ar)
  (public_name stdnum.ar)
- (libraries stdnum.tools))
+ (modules cbu)
+ (libraries tools))

lib/dune

@@ -1,3 +1,4 @@
 (library
  (name stdnum)
- (public_name stdnum))
+ (public_name stdnum)
+ (modules_without_implementation stdnum))

lib/hu/dune

@@ -1,4 +1,5 @@
 (library
  (name hu)
+ (public_name stdnum.hu)
  (modules anum)
  (libraries tools))

lib/iso7064/dune

@@ -1,4 +1,5 @@
 (library
  (name iso7064)
+ (public_name stdnum.iso7064)
  (modules mod_37_2 mod_97_10)
  (libraries tools))

lib/pl/dune

@@ -1,4 +1,5 @@
 (library
  (name pl)
+ (public_name stdnum.pl)
  (modules nip pesel regon)
  (libraries tools))

lib/stdnum.mli

@@ -0,0 +1,124 @@
+(** {1 Standard Number Validation Library}
+
+    OCaml library to provide functions to handle, parse and validate standard numbers.
+
+    This library supports validation of various standard numbers including:
+    - National identification numbers
+    - Tax identification numbers  
+    - Bank account numbers
+    - ISBN/ISSN codes
+    - And many more
+
+    {2 Organization}
+
+    The library is organized by country/region modules:
+    - Us - United States numbers (ATIN, etc.)
+    - Pl - Polish numbers (PESEL, NIP, REGON, etc.)  
+    - Al - Albanian numbers (NIPT)
+    - Ad - Andorran numbers (NRT)
+    - Ar - Argentine numbers (CBU)
+    - Hu - Hungarian numbers (ANUM)
+
+    And utility modules:
+    - Tools - Common utility functions
+    - Iso7064 - ISO 7064 checksum algorithms
+
+    {2 Usage Examples}
+
+    {3 Polish Numbers}
+    {[
+      (* Polish NIP (VAT number) validation *)
+      let nip = "123-456-78-90" in
+      if Pl.Nip.is_valid nip then
+        Printf.printf "Valid NIP: %s\n" (Pl.Nip.format nip)
+      else
+        Printf.printf "Invalid NIP\n"
+
+      (* Polish PESEL (national ID) validation *)
+      let pesel = "44051401359" in
+      try
+        let validated = Pl.Pesel.validate pesel in
+        Printf.printf "Valid PESEL: %s\n" (Pl.Pesel.format validated)
+      with
+      | Pl.Pesel.Invalid_format -> Printf.printf "Invalid PESEL format\n"
+      | Pl.Pesel.Invalid_checksum -> Printf.printf "Invalid PESEL checksum\n"
+
+      (* Polish REGON (business number) validation *)
+      let regon = "123456785" in
+      assert (Pl.Regon.is_valid regon);
+      Printf.printf "Formatted REGON: %s\n" (Pl.Regon.format regon)
+    ]}
+
+    {3 US Numbers}
+    {[
+      (* US ATIN (Adoption Taxpayer ID) validation *)
+      let atin = "900-93-0000" in
+      if Us.Atin.is_valid atin then
+        Printf.printf "Valid ATIN: %s\n" atin
+      else
+        Printf.printf "Invalid ATIN\n"
+    ]}
+
+    {3 Argentine Numbers}
+    {[
+      (* Argentine CBU (bank account) validation *)
+      let cbu = "0170016212000012345678" in
+      try
+        let validated = Ar.Cbu.validate cbu in
+        Printf.printf "Valid CBU: %s\n" (Ar.Cbu.format validated)
+      with
+      | Ar.Cbu.Invalid_format -> Printf.printf "Invalid CBU format\n"
+      | Ar.Cbu.Invalid_checksum -> Printf.printf "Invalid CBU checksum\n"
+    ]}
+
+    {3 Albanian Numbers}
+    {[
+      (* Albanian NIPT (tax number) validation *)
+      let nipt = "J91402501L" in
+      if Al.Nipt.is_valid nipt then
+        Printf.printf "Valid NIPT: %s\n" (Al.Nipt.format nipt)
+      else
+        Printf.printf "Invalid NIPT\n"
+    ]}
+
+    {3 Utility Functions}
+    {[
+      (* Using utility functions *)
+      let number = "123-45-6789" in
+      let cleaned = Tools.Utils.clean number "-" in
+      Printf.printf "Cleaned: %s\n" cleaned; (* "123456789" *)
+
+      let is_numeric = Tools.Utils.is_digits cleaned in
+      Printf.printf "Is numeric: %b\n" is_numeric; (* true *)
+    ]}
+
+    {3 ISO 7064 Checksums}
+    {[
+      (* Using ISO 7064 checksum algorithms *)
+      let number = "12345678" in
+      let checksum = Iso7064.Mod_97_10.checksum number in
+      Printf.printf "ISO 7064 MOD 97-10 checksum: %d\n" checksum;
+
+      let with_check = Iso7064.Mod_37_2.checksum "ABCDEFGH" in
+      Printf.printf "ISO 7064 MOD 37-2 checksum: %d\n" with_check
+    ]}
+
+    {2 Common Patterns}
+
+    Most modules in this library follow a consistent interface:
+    - [validate] - validates and returns normalized form, raises exception on invalid
+    - [is_valid] - returns boolean, never raises exceptions
+    - [format] - formats number to standard presentation
+    - [compact] - removes formatting characters
+    - [checksum] - calculates checksum (where applicable)
+
+    {2 Error Handling}
+
+    The library uses OCaml exceptions for error handling:
+    - [Invalid_format] - number format is incorrect
+    - [Invalid_length] - number has wrong length
+    - [Invalid_checksum] - checksum validation failed
+
+    Use [is_valid] functions for boolean checks without exceptions,
+    or [validate] functions with proper exception handling.
+*)