From b56371994f5d3f5c1aa5d63c28efd18856ea8e9b Mon Sep 17 00:00:00 2001
From: retoor <retoor@molodetz.nl>
Date: Fri, 24 Jan 2025 23:41:54 +0100
Subject: [PATCH] Added docs.

---
 src/snek/docs/__pycache__/app.cpython-312.pyc | Bin 0 -> 2268 bytes
 src/snek/docs/app.py                          |  33 +++++
 src/snek/docs/docs/api.html                   |  61 +++++++++
 src/snek/docs/docs/base.html                  | 116 ++++++++++++++++++
 src/snek/docs/docs/form_api_javascript.html   |  17 +++
 src/snek/docs/docs/form_api_python.html       |  92 ++++++++++++++
 src/snek/docs/docs/index.html                 |  37 ++++++
 7 files changed, 356 insertions(+)
 create mode 100644 src/snek/docs/__pycache__/app.cpython-312.pyc
 create mode 100644 src/snek/docs/app.py
 create mode 100644 src/snek/docs/docs/api.html
 create mode 100644 src/snek/docs/docs/base.html
 create mode 100644 src/snek/docs/docs/form_api_javascript.html
 create mode 100644 src/snek/docs/docs/form_api_python.html
 create mode 100644 src/snek/docs/docs/index.html

diff --git a/src/snek/docs/__pycache__/app.cpython-312.pyc b/src/snek/docs/__pycache__/app.cpython-312.pyc
new file mode 100644
index 0000000000000000000000000000000000000000..087bb64a5ffd1d887e3c44a479e90e0aff6c268a
GIT binary patch
literal 2268
zcmb_dO>7fK6rS;}?R6aELfo=x(vk`Vv9#F8stQF3rO;9#AgVxWkuS^Qosf0xT{APz
zAC81d)H)LVL81*kl|v6yp%O>#Tw3+em;^bRf{N5uYNZ~KQYyru>YKGU1cTH|pR_ac
z-kW**X6Ak0{E$d=AdsK6i>G#n5&A_cfq?GI%2DX%kd16yL?xUHVL1*Jm7D^-QdCRf
zT-dj%#Yicdi~8d*jJ2GGQ3$<*?8pqVqa-x1G(+a_WXRC|kcxpt{LON?=;ST#c<vDB
z$~ZX*-TEUI9kso2_w5NzTn0`sCMj`kLd{akmv07awyo%BWeeyZLCyr_u#IvdTdAR8
zY~z_2<Q$qoIkko+a4vid87h^l@}V_x<i?Zmt^5Pc=Xefr9C!<B=e3MgJm2zHk-6%x
zqJkQ%del#=JQ`@T;VSz08HB1K8&_2aSCy~vCm17G>0e4Puh|z8kLyz7>jGPlfxjAJ
zwo9R_-Gbl>;ZLb2?encYU^IygWk@7ADV2*BCuZ5=BU2rjGu(2DyVKjIjkt(PThTcw
z)OTSZRH=$EtCR^9nrS+&!%b6k6dbo;WliFaiG*d_CJC;T%EJ~B>Qy+bh)Uln!bNh#
za_u59Z7*Lb5tkbgp)yh&rk!%SYSB|nL`KJDPh-*)GtGR_V$3vI1oS>BXCFSF$$K`*
zFq+RWmyBj09Lreca=JW8<=IW8)|6g4NLQXdI|0puv*>oJXYTNY!<SQwsVz12d~8|o
z{VMiltd{syOUy>=ntqKhXa_D&LvwxXrgmUi>-;o1n`~(Pb*+DC%g!Zj*Ih8hXX6d6
zr>^x}I(#M7Fb3<!;4N*>3jE{o(v!t;4!)H?p`;EW3^iQE1v#xvY}^f&LQwH*ymlxk
zhUpNLmNL2(AsVt((4Jb7h1G(56r}nnhEi1u@`T%DzNIsr#{*YEUQV0XVLM_+uWAAE
zk0FRB!PO=~Jh~qIPszwuS9kUQXM_st+tLA*uR;bgdiF{G(@!(VGU$OET5viCta%3R
z>x<Bw@?kiPrq!x?4DCecBi}0H*oX}YRpLtEj6hQz4zS!rdW4sX&P6B%)(;6BCCsbP
zJn3^-pX>3yVXxxaeV*ILN5H}e9V0Y7)xiN=833%~8j6T8Zt)5e>PgR@6rFj`1uo?#
zpDYtVZ%4`E`4K?rum_;!)G0RsrWHKL^`RUg6At5yN-h%`WKi~8MnuG6rtQ#GIu0m8
zC=f-&DFME4#)!#1BTOa7h$tneD}-^8Sate8NCXh~*+poy^$RA6!G|%`VMOI^O!cgV
zYa2z#3G5a$zf0UM>zf+-wz|IU%4>B!+t7E_^<CGy7WKheVmYo~+IKVl;&SiS+L0EX
zTXP2&_19rSvbT}kTu*LZO7`FGdTwsu!oX#=u;ci`FkR|m3!MxiG~%1;@l8wdmzH~t
zMsK#>o4q!$*t-`3{@3EW-7hq{x7WM3U(H|J-pC%RXAgb%){h6jKe(8EZ!!J;!f|u4
z`$VJbL`_>xZmcEmDJW&(hin7v?1TNr{#Wshm+}6rdgGNSj14>l)CffDS|uWh)-+3=
zT><7aMW<<=u2{vU$EQ305JjRzm3dMunx=v2MtO4b3ESH|YDp^otEfqbe0Ltqp!;ex
z{KnrK5@DT6=JEYT3>X{O6h2=U$$b_hYwn0jDup?YH^O<jSwtzx#A!Ckpk~s+GwweF
zR5JHBs2N{gy3huiyV*l`f+|yFebC%fFvfRK_9wLN4%!HV-_VY~R2}P|W$q*B{0RR7
DYoG_%

literal 0
HcmV?d00001

diff --git a/src/snek/docs/app.py b/src/snek/docs/app.py
new file mode 100644
index 0000000..5e00d98
--- /dev/null
+++ b/src/snek/docs/app.py
@@ -0,0 +1,33 @@
+from app.app import Application as BaseApplication
+import pathlib 
+from aiohttp import web
+from snek.system.markdown import MarkdownExtension
+
+from snek.system.markdown import render_markdown 
+
+class Application(BaseApplication):
+
+    def __init__(self, path=None, *args,**kwargs):
+        self.path = pathlib.Path(path)
+        template_path = self.path
+
+        super().__init__(template_path=template_path ,*args, **kwargs)
+        self.jinja2_env.add_extension(MarkdownExtension) 
+        
+        self.router.add_get("/{tail:.*}",self.handle_document)
+
+    async def handle_document(self, request):
+        relative_path = request.match_info['tail'].strip("/")
+        if relative_path == '':
+            relative_path = 'index.html'
+        document_path = self.path.joinpath(relative_path)
+        if not document_path.exists():
+            return web.Response(status=404,body=b'Resource is not found on this server.',content_type="text/plain")
+        if document_path.is_dir():
+            document_path = document_path.joinpath("index.html")
+        if not document_path.exists():
+            return web.Response(status=404,body=b'Resource is not found on this server.',content_type="text/plain")
+        
+        response = await self.render_template(str(document_path.relative_to(self.path)),request)
+        return response
+
diff --git a/src/snek/docs/docs/api.html b/src/snek/docs/docs/api.html
new file mode 100644
index 0000000..e30a99d
--- /dev/null
+++ b/src/snek/docs/docs/api.html
@@ -0,0 +1,61 @@
+{% extends "docs/base.html" %}
+
+{% block main %}
+{% markdown %}
+
+# API Documentation
+
+Currently only some details about the internal API are available.
+
+## How to create a user
+```python
+# Save user to the table named 'user'
+# Password gets sha256 encrypted with default a salt string
+# of the snek.system.security module.
+
+new_user_object = await app.service.user.register(
+    username="retoor", 
+    password="retoorded"
+)
+```
+
+## Encrypt string
+```python
+from snek.system import security
+
+# Support for both utf and bytes.
+var1 = security.encrypt("data")
+var2 = security.encrypt(b"data")
+
+# Is correct:
+assert(var1 == var2)
+```
+
+## How to create a basic HTML / Markdown view
+```python
+from snek.system.view import BaseView 
+
+class IndexView(BaseView):
+    
+    async def get(self):
+        # The render function supports markdown.
+        # It will render with syntax highlighting.
+        # Just use the .md file extension in the file name.
+        return await self.render("index.html")
+```
+## How to create a FormView
+```python
+from snek.system.view import BaseFormView
+from snek.form.register import RegisterForm
+
+class RegisterFormView(BaseFormView):
+    
+    form = RegisterForm
+```
+## How to register a class view
+```python
+app.routes.add_view("/your-page.html", YourViewClass)
+```
+
+{% endmarkdown %}
+{% endblock %}
\ No newline at end of file
diff --git a/src/snek/docs/docs/base.html b/src/snek/docs/docs/base.html
new file mode 100644
index 0000000..7c53bec
--- /dev/null
+++ b/src/snek/docs/docs/base.html
@@ -0,0 +1,116 @@
+<html>
+
+<head>
+    <style>{{ highlight_styles }}</style>
+    <style>
+        
+        * {
+
+            box-sizing: border-box;
+        }
+
+        .dialog {
+
+            background-color: #0f0f0f;
+            border-radius: 10px;
+            padding: 30px;
+            width: 800px;
+            margin: 30px;
+            box-shadow: 0 0 15px rgba(0, 0, 0, 0.5);
+        }
+
+        @media screen and (max-width: 500px) {
+            .center {
+                width: 100%;
+                left: 0px;
+            }
+
+            .dialog {
+                width: 100%;
+                left: 0px;
+            }
+
+        }
+
+        h1 {
+            font-size: 2em;
+            color: #f05a28;
+            margin-bottom: 20px;
+        }
+
+        h2 {
+            font-size: 1.4em;
+            color: #f05a28;
+            margin-bottom: 20px;
+        }
+
+        html,body,main {
+            font-family: Arial, sans-serif;
+            background-color: #1a1a1a;
+            color: #e6e6e6;
+            line-height: 1.5;
+            display: flex;
+            flex-direction: column;
+            align-items: center;
+            min-height: 100vh;
+            width: 100%;
+        }
+        article {
+            max-width: 100%;
+            width: 60%;
+            background-color: #0f0f0f;
+            padding: 30px;
+            min-height: 100vh;
+            word-break: break-all;
+        }
+        footer {
+            position: fixed;
+            width: 60%;
+            text-align: center; 
+            bottom: 0;
+            left: 20%;
+            background-color: #000;
+        }
+        a {
+    color: #f05a28;
+    display: block;
+    margin-top: 15px;
+    font-size: 0.9em;
+    transition: color 0.3s;
+  }
+  header {
+
+    text-align: left;
+    width: 60%;
+    padding: 30px;
+  }
+  header a {
+    display: inline;
+
+  }
+        div {
+            text-align: left;
+
+        }
+    </style>
+</head>
+
+<body>
+    <main>
+        <header>
+            <a href="/">Snek</a>
+            <a href="/docs/docs">Docs</a>
+        </header>
+      <article>
+            {% block main %}
+            {% endblock %}
+        </article>
+    </main>
+    <footer>
+        {% markdown %}
+        [Respository](https://github.com/retoor/snek)
+        {% endmarkdown %}
+    </footer>
+</body>
+
+</html>
\ No newline at end of file
diff --git a/src/snek/docs/docs/form_api_javascript.html b/src/snek/docs/docs/form_api_javascript.html
new file mode 100644
index 0000000..c83ee7f
--- /dev/null
+++ b/src/snek/docs/docs/form_api_javascript.html
@@ -0,0 +1,17 @@
+{% extends "docs/base.html" %}
+
+{% block main %}
+{% markdown %}
+# Form API Javascript 
+
+## Dependencies
+ - generic-form.js 
+
+## Usage 
+It's just a HTML component that can be declared using an one liner. Buttons and title are specified server side.
+```html 
+<generic-form url="/url-to-form-api"></generic-form>
+```
+
+{% endmarkdown %}
+{% endblock %}
\ No newline at end of file
diff --git a/src/snek/docs/docs/form_api_python.html b/src/snek/docs/docs/form_api_python.html
new file mode 100644
index 0000000..d7e67bc
--- /dev/null
+++ b/src/snek/docs/docs/form_api_python.html
@@ -0,0 +1,92 @@
+{% extends "docs/base.html" %}
+
+{% block main %}
+{% markdown %}
+# Form API Javascript 
+
+## Dependencies
+ - `snek.system.form.Form`
+ - `snek.system.form.HTMLElement`
+ - `snek.system.form.FormInputElement`
+ - `snek.system.form.FormButtonElement`
+
+## Usage 
+Here is an example with custom validation. 
+This example contains a field that checks if user already exists. 
+If invalid, it adds an error message which automatically invalidates the field. 
+Handling of the error messages will automatically done client side.
+
+Forms are usaly located in `snek/form/[form name].py`.
+
+```python
+from snek.system.form import Form, HTMLElement,FormInputElement,FormButtonElement
+
+class UsernameField(FormInputElement):
+
+    @property
+    async def errors(self):
+        result = await super().errors
+        if self.value and await self.app.services.user.count(username=self.value):
+            result.append("Username is not available.")
+        return result
+
+class RegisterForm(Form):
+
+    title = HTMLElement(tag="h1", text="Register")
+
+    username = UsernameField(
+        name="username", 
+        required=True,
+        min_length=2,
+        max_length=20,
+        regex=r"^[a-zA-Z0-9_]+$",
+        place_holder="Username",
+        type="text"
+    )
+    email = FormInputElement(
+        name="email",
+        required=False,
+        regex=r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$",
+        place_holder="Email address",
+        type="email"
+    )
+    password = FormInputElement(
+        name="password",
+        required=True,
+        regex=r"^[a-zA-Z0-9_.+-]{6,}",
+        type="password",
+        place_holder="Password"
+    )
+    action = FormButtonElement(
+        name="action",
+        value="submit",
+        text="Register",
+        type="button"
+    )
+```
+
+## Set data 
+
+```python 
+# The input structure is in same format as output structure.
+# Output structure is the result of await form.to_json()
+data = dict(
+    username=dict(value="retoor"),
+    password=dict(value="retoorded")
+)
+form.set_user_data(data)
+
+# Check if form is valid.
+is_valid = await form.is_valid
+
+# Convert form to a record (kv pairs) to be used for persistance. 
+# It does contain an filled uid (UUID4) field already to be used as primary key.
+# Default fields:
+# - uid (automatically generated, it's an UUID4 wich you can use as private key for database)
+# - created_at (automatically generated, it's a string representation of UTC locale)
+# - updated_at (execute await form.updated_at.update() before saving to set value)
+key_value_values = await form.record 
+```
+
+{% endmarkdown %}
+{% endblock %}
\ No newline at end of file
diff --git a/src/snek/docs/docs/index.html b/src/snek/docs/docs/index.html
new file mode 100644
index 0000000..8ced8ab
--- /dev/null
+++ b/src/snek/docs/docs/index.html
@@ -0,0 +1,37 @@
+{% extends "docs/base.html" %}
+
+{% block main %}
+{% markdown %}
+# Snek
+
+# Introduction
+
+Snek is a high customizable chat application. 
+It is made because Rocket Chat didn't fit my needs anymore. It became bloathed and very heavy commercialized. You would get upsell messages on your locally hosted instance!
+
+This documentation is under construction. Only the form API and the small introduction is a bit documented.
+
+## Quick API notes 
+[Small introduction / cheatsheet](/docs/docs/api.html)
+
+## View API
+With the view classes of Snek you can render HTML and Markdown 
+ - [API Python](#)
+ - [API Javascript](#)
+
+## ORM API
+Snek's database model is based on Python dataset library. 
+Snek uses a model/mapper architecture build on top of that library.
+ - [API](#)
+
+## Form API
+Snek does have his own components for creating and rendering forms. 
+All forms are made server side and client side is generated client side using a HTML component.
+It's client side only one line to include a form that can validate and submit.
+Validation is server side using REST. Page won't refresh.
+[API Python](/docs/docs/form_api_python.html) 
+[API Javascript](/docs/docs/form_api_javascript.html)
+
+
+{% endmarkdown %}
+{% endblock %}
\ No newline at end of file