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,36 @@
+<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 welcomed if not
+breaking `kibit`.
+
+## Submitting a PR
+
+Before you are submitting 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
+- Follow [Semantic Versioning 2.0.0](https://semver.org/#semantic-versioning-200)
 
 ## Development dependencies
 
@@ -31,12 +58,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 +107,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 using [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 for 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. For use, you need to
+
+```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,16 +1,24 @@
+<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
@@ -49,11 +57,11 @@ 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.
 
@@ -64,5 +72,20 @@ 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. 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, 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 and `:error` handler, it will call it, otherwise it'll search for `:error`
+handlers for the beginning of the interceptor queue. When and `:error` function found, and matched with the given
+exception, the executor calls the queue `:leave` functions in reserved order, where the handler has been found.
+
+This diagram shows how the error cases handled:
+![diagram](./conventions-3.svg)