Update documentation

.gitignore

@@ -121,3 +121,5 @@ pom.xml.asc
 .clj-kondo/*
 !.clj-kondo/config.edn
 *.iml
+/node_modules/
+/package.json

README.md

@@ -1,9 +1,10 @@
-![Xiana logo](resources/images/Xiana.png)
+![Xiana logo](doc/resources/images/Xiana.png)
+
 # Xiana framework
 
 Xiana is a lightweight web-application framework written in Clojure, for Clojure. The goal is to be simple, fast, and
-most importantly - a welcoming platform for web programmers with different backgrounds who want to experience the wonders
-of functional programming!
+most importantly - a welcoming platform for web programmers with different backgrounds who want to experience the
+wonders of functional programming!
 
 It's easy to install, fun to experiment with, and a powerful tool to produce monolithic web applications.
 
@@ -16,7 +17,9 @@ Xiana has its own Leiningen template, so you can create a skeleton project with
 ```shell
 lein new xiana app
 ```
-[getting-started](./doc/getting-started.md) explains how to use this to create a very simple app with a db, a backend offering an API, and a frontend that displays something from the database.
+
+[getting-started](./doc/getting-started.md) explains how to use this to create a very simple app with a db, a backend
+offering an API, and a frontend that displays something from the database.
 
 ### As a dependency
 
@@ -28,8 +31,6 @@ Add it to your project as a dependency from clojars:
 
 - First check out the [conventions](./doc/conventions.md).
 - To start working with xiana, read the [tutorials](./doc/tutorials.md).
-- A hands-on approach in the [how-to](./doc/How-To.md)s.
-- Check the available [modules](./doc/modules.md), and [interceptors](./doc/interceptors.md).
 - To contribute, see the [contribution](./doc/contribution.md) docs.
 
 ### Examples
@@ -45,5 +46,7 @@ Visit [examples folder](examples), to see how you can perform
 ## References
 
 ### Concept of interceptors
+
 http://pedestal.io/reference/interceptors
+
 https://github.com/metosin/sieppari

deps.edn

@@ -39,13 +39,20 @@
   {:extra-deps {clj-kondo/clj-kondo {:mvn/version "2022.05.31"}}
    :main-opts  ["-m" "clj-kondo.main" "--lint" "src"]}
 
-  :codox {:extra-deps {codox/codox {:mvn/version "0.10.8"}}
+  :codox {:extra-deps  {codox/codox {:mvn/version "0.10.8"}}
           :extra-paths ["resources"]
-          :exec-fn    codox.main/generate-docs
-          :exec-args  {:output-path  "docs/new/"
-                       :themes       [:default :xiana]
-                       :source-paths ["src"]
-                       :doc-files    ["doc/getting-started.md", "doc/How-To.md", "doc/Development-Guide.md"]}}
+          :exec-fn     codox.main/generate-docs
+          :exec-args   {:output-path  "docs/new/"
+                        :themes       [:default :xiana]
+                        :metadata     {:doc/format :markdown}
+                        :source-uri   "https://github.com/Flexiana/framework/blob/{git-commit}/{filepath}#L{line}"
+                        :source-paths ["src"]
+                        :doc-files    ["doc/welcome.md"
+                                       "doc/conventions.md"
+                                       "doc/tutorials.md"
+                                       "doc/how-to.md"
+                                       "doc/contribution.md"
+                                       "doc/getting-started.md"]}}
 
   :kibit
   {:extra-deps {tvaughan/kibit-runner {:mvn/version "1.0.1"}}

doc/contribution.md

@@ -1,9 +1,37 @@
+<img src="resources/images/Xiana.png" width="242">
+
 # Contribution
 
+- [Ticket system](#ticket-system)
+- [Coding standards](#coding-standards)
+- [Submitting a PR](#submitting-a-pr)
 - [Development dependencies](#development-dependencies)
 - [Setup](#setup)
 - [Deps](#deps)
 - [Releasing](#releasing)
+- [Generating API docs](#generating-api-docs)
+
+## Ticket system
+
+We're using GitHub [issues](https://github.com/Flexiana/framework/issues) for tracking and discussing ideas and
+requests.
+
+## Coding standards
+
+Please follow `clj-style` and `kondo` instructions. `Kibit` isn't a showstopper, but PRs are more welcome if they don't
+break `kibit`.
+
+## Submitting a PR
+
+Before you submit a PR be sure:
+
+- You've updated the documentation and the [CHANGELOG](../CHANGELOG.md)
+- the PR has an issue in GitHub, with a good description
+- you have added tests
+- you provided an example project for a new feature
+
+All PRs need at least two approvals and pls
+follow [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
 
 ## Development dependencies
 
@@ -31,12 +59,8 @@
 | nilenso/honeysql-postgres       | 0.2.6   | PostGreSQL          |
 | org.postgresql/postgresql       | 42.2.2  | PostGreSQL          |
 | crypto-password/crypto-password | 0.2.1   | Security            |
-
-#### Optional
-
-| Name                | Version | Provide |
-|---------------------|---------|---------|
-| clj-kondo/clj-kondo | RELEASE | Tests   |
+| clj-kondo/clj-kondo             | RELEASE | Tests               |
+| npx                             | RELEASE | Documentation       |
 
 ## Setup
 
@@ -84,4 +108,38 @@ clj -M:install
 
 - Be sure all examples has the same framework version as it is in `release.edn` as dependency
 - Execute `./example-tests.sh` script. It will install the actual version of xiana, and go through the examples folder
-  for `check-style` and `lein test`. 
+  for `check-style` and `lein test`.
+
+## Generating API Docs
+
+This is done with [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) and a forked version
+of [Codox](https://github.com/Flexiana/codox).
+
+We're using mermaid-cli to render UML-diagrams in markdown files, see the `doc/conventions_template.md` for example.
+These files need to be added to the `/script/build-docs.sh` . For using it you need to have `npx`.
+
+Codox is forked because markdown anchors aren't converted to HTML anchors in the official release. To use it you need
+
+```shell
+git clone [email protected]:Flexiana/codox.git
+cd codox/codox
+lein install
+```
+
+it before generating the documentation.
+
+To generate or update the current version run the script:
+
+```shell
+./script/build-docs.sh
+```
+
+This runs the following:
+
+```shell
+npx -py @mermaid-js/mermaid-cli mmdc -i doc/conventions_template.md -o doc/conventions.md
+clj -X:codox
+mv docs/new docs/{{version-number}}
+```
+
+It also updates the index.html file to point to the new version.

doc/conventions.md

@@ -1,21 +1,29 @@
+<img src="resources/images/Xiana.png" width="242">
+
 # Conventions
 
+- [Overview](#overview)
 - [State](#state)
 - [Action](#action)
 - [Handler](#handler)
 - [Dependencies](#dependencies)
 - [Interceptors](#interceptors)
+- [Interceptors error handling](#interceptors-error-handling)
+
+## Overview
 
+The diagram bellow gives you an overview how a request is processed in Xiana based applications.
+![diagram](./conventions-1.svg)
 ## State
 
-A state record. It is created for each HTTP request and represents the current state of the application. It contains:
+State is created for each HTTP request and represents the current state of the application. It contains:
 
-- the application's dependencies
+- the application's dependencies and configuration
 - request
 - request-data
 - response
 
-This structure is very volatile, will be updated quite often on the application's life cycle.
+This structure is very volatile, and will be updated quite often on the application's life cycle.
 
 The main modules that update the state are:
 
@@ -25,7 +33,7 @@ The main modules that update the state are:
 
 - Interceptors:
 
-  Add, consumes or remove information from the state map. More details in [Interceptors](#interceptors) section.
+  Add, consume or remove information from the state map. More details in [Interceptors](#interceptors) section.
 
 - Actions:
 
@@ -39,7 +47,7 @@ The state is renewed on every request.
 
 The action conventionally is the control point of the application flow. This is the place were you can define how the
 rest of your execution flow would behave. Here you can provide the database query, restriction function, the view, and
-the additional side effect functions are you want to execute.
+the additional side effect functions that you want to execute.
 
 Actions are defined in the routes vector
 
@@ -49,20 +57,35 @@ Actions are defined in the routes vector
 
 ## Handler
 
-Xiana's handler does all the processing. It runs on every request and does the following. It creates the state for every
-request, matches the appropriate route, executes the interceptors, handles interceptor overrides, and not-found cases.
+Xiana's handler creates the state for every request, matches the appropriate route, executes the interceptors, handles
+interceptor overrides, and not-found cases.
 It handles websocket requests too.
 
-### Routing
+## Routing
 
 Routing means selecting the actions to execute depending on the request URL, and HTTP method.
 
 ## Dependencies
 
-Modules can depend on external resources, configurations, as well as on other modules. These dependencies are added to
+Modules can depend on external resources and configurations, as well as on other modules. These dependencies are added to
 the state on state creation, and defined on application startup.
 
 ## Interceptors
 
-An interceptor is a pair of unary functions. Each function must recieve and return a state map. You can look at it as on an analogy to AOP's around aspect, or as on a pair of middlewares. They work mostly the same way as [pedestal](http://pedestal.io/reference/interceptors) and [sieppari](https://github.com/metosin/sieppari) interceptors.
-Xiana provides a set of base [interceptors](interceptors.md), for the most common use cases. 
+An interceptor is a pair of unary functions. Each function must recieve and return a state map. Look at it as an analogy
+to AOP's around aspect, or as on a pair of middlewares. They work mostly the same way
+as [pedestal](http://pedestal.io/reference/interceptors) and [sieppari](https://github.com/metosin/sieppari)
+interceptors.
+Xiana provides a set of base interceptors, for the most common use cases.
+
+This figure shows how interceptors are executed ideally:
+![diagram](./conventions-2.svg)
+## Interceptors error handling:
+
+The interceptor executor handles the exceptional states like sieppari does. If an exception happens, it tries to handle
+first in the same interceptor. If it has an `:error` handler, it will call it, otherwise it'll search for `:error`
+handlers from the beginning of the interceptor queue. When an `:error` function found, and matched with the given
+exception, the executor calls the queue of `:leave` functions in reserved order from where the handler was found.
+
+This diagram shows how the error cases are handled:
+![diagram](./conventions-3.svg)