Update documentation #238

g-krisztian · 2022-10-06T10:35:45Z

Title:

Update documentation for release v0.5.0-rc3

Description

Updated markdown files, and build-docs.sh to support UML integration
Using forked codox for support markdown anchors - See in contribution.md

Tester info

Pls go through as an english teacher 😉

Completion Checklist

Add description of the changes made here to the changelog file
Update the documentation as necessary

soulflyer · 2022-10-07T15:25:38Z

doc/contribution.md

+
+## Coding standards
+
+Please follow `clj-style` and `kondo` instructions. `Kibit` isn't a showstopper, but PRs are more welcomed if not


"...more welcome if they don't break kibit.'

soulflyer · 2022-10-07T15:26:21Z

doc/contribution.md

+
+## Submitting a PR
+
+Before you are submitting a PR be sure:


"Before you submit a PR be sure:"

soulflyer · 2022-10-07T15:28:06Z

doc/contribution.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


This doesn't really belong in a list of things to check. Maybe just move it to its own paragraph after the list.

soulflyer · 2022-10-07T15:29:06Z

doc/contribution.md

+## Generating API Docs
+
+This is done with using [mermaid-cli](https://github.com/mermaid-js/mermaid-cli) and a forked version


either "with" or "using". Not both.

soulflyer · 2022-10-07T15:29:53Z

doc/contribution.md

+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.


"...mermaid-cli to render..."

soulflyer · 2022-10-07T15:30:20Z

doc/contribution.md

+
+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`.


"To use it you need...."

soulflyer · 2022-10-07T15:31:37Z

doc/conventions.md


+The diagram bellow gives you an overview, how a request is processed in Xiana based applications.


"... an overview of how a request..."

soulflyer · 2022-10-07T15:32:33Z

doc/conventions.md

@@ -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


"look at it as an analogy...."

soulflyer · 2022-10-07T15:33:51Z

doc/conventions.md

+## 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`


"If it has an..."

soulflyer · 2022-10-07T15:34:42Z

doc/conventions.md

+
+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


Should "for" be "from"?
"When an :error function..."

soulflyer · 2022-10-07T15:36:20Z

doc/conventions.md

+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.


maybe "...calls the queue of :leave functions in reverse order from where the handler was found.

soulflyer · 2022-10-07T15:36:47Z

doc/conventions.md

+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:


"..cases are handled:"

soulflyer · 2022-10-07T15:38:07Z

doc/conventions_template.md

+- request-data
+- response
+
+This structure is very volatile, will be updated quite often on the application's life cycle.


"...volatile, and will be updated..."

soulflyer · 2022-10-07T15:38:33Z

doc/conventions_template.md

+
+- Interceptors:
+
+  Add, consumes or remove information from the state map. More details in [Interceptors](#interceptors) section.


soulflyer · 2022-10-07T15:39:31Z

doc/conventions_template.md

+
+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.


"...functions that you want to..."

soulflyer · 2022-10-07T15:41:12Z

doc/conventions_template.md

+
+## Dependencies
+
+Modules can depend on external resources, configurations, as well as on other modules. These dependencies are added to


"...external resources and configurations..." (or maybe and/or)

soulflyer · 2022-10-07T15:42:51Z

doc/conventions_template.md

+
+## 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


"...look at it as an analogy..."

soulflyer · 2022-10-07T15:44:25Z

doc/conventions_template.md

+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.


Same as the non template version.

soulflyer · 2022-10-07T15:46:51Z

doc/getting-started.md

  ...
  )
 ```

 ### 2. Set initial value of re-frame database

-File *src/frontend/todo_app/db.cljs* contains initial value of re-frame databse. Inside of this file replace value of *default-db* to following:
+File *src/frontend/todo_app/db.cljs* contains initial value of re-frame databse. Inside of this file replace value of *


"...change the value of default-db to the following..."

soulflyer · 2022-10-07T15:51:36Z

docs/0.5.0-rc2/contribution.html

@@ -0,0 +1,108 @@
+<!DOCTYPE html PUBLIC ""


This will need regenerating from the corrected .md file?

soulflyer

LGTM

Krisztian Gulyas added 7 commits September 27, 2022 11:13

Update documentation

2573260

Update version

0370d06

Add version-docs

0be8e20

Add source uri

26aba45

update README.md xiana logo

71a4edc

Merge branch 'main' into update_documentation

08d34d2

Update docs

e6fad22

soulflyer reviewed Oct 7, 2022

View reviewed changes

doc/contribution.md Outdated

## Submitting a PR

Before you are submitting a PR be sure:

Copy link

Contributor

soulflyer Oct 7, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Before you submit a PR be sure:"

soulflyer reviewed Oct 7, 2022

View reviewed changes

Language review @soulflyer

32e99f8

soulflyer reviewed Nov 7, 2022

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update documentation #238

Update documentation #238

g-krisztian commented Oct 6, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022 •

edited

Loading

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer Oct 7, 2022

soulflyer left a comment


		## Coding standards

		Please follow `clj-style` and `kondo` instructions. `Kibit` isn't a showstopper, but PRs are more welcomed if not

		## 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.


		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`.


		The diagram bellow gives you an overview, how a request is processed in Xiana based applications.


		- Interceptors:

		Add, consumes or remove information from the state map. More details in [Interceptors](#interceptors) section.


		## Dependencies

		Modules can depend on external resources, configurations, as well as on other modules. These dependencies are added to


		## 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

Update documentation #238

Are you sure you want to change the base?

Update documentation #238

Conversation

g-krisztian commented Oct 6, 2022

Title:

Description

Tester info

Completion Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

soulflyer Oct 7, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

soulflyer left a comment

Choose a reason for hiding this comment

soulflyer Oct 7, 2022 •

edited

Loading