Feature/suggestions_docs (#21)

* feat(docs): added night mode * feat(docs): changed example to mermaid diagram * feat(docs): landing page suggestions * feat(doc): coquilles et custom admonition * Update docs/pages/a_simple_example.md Co-authored-by: develop-cs <[email protected]> Signed-off-by: NinaPetard <[email protected]> * Update README.md Signed-off-by: NinaPetard <[email protected]> * fix: doc typo Signed-off-by: develop-cs <[email protected]> --------- Signed-off-by: NinaPetard <[email protected]> Signed-off-by: develop-cs <[email protected]> Co-authored-by: PETARD Nina <[email protected]> Co-authored-by: develop-cs <[email protected]>
MAIF · Jun 18, 2024 · cc9743c · cc9743c
1 parent b4e4f58
commit cc9743c
Show file tree

Hide file tree

Showing 10 changed files with 103 additions and 46 deletions.
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@
 
 ### Goal
 
-There is one main reason for using **Arta** and it was the main goal of its development at *MAIF*: increase business rules maintainability.
+There is one main reason for using **Arta** and it was the main goal behind its development at *MAIF*: increase business rules maintainability.
 
 In other words, facilitate rules handling in our python apps.
 

diff --git a/docs/mkdocs.yaml b/docs/mkdocs.yaml
@@ -9,8 +9,31 @@ theme:
   logo: assets/img/arta-fond-clair.svg
   favicon: assets/img/arta-git.svg
   palette:
-    primary: white
-    accent: red
+    # Palette toggle for automatic mode
+    - media: "(prefers-color-scheme)"
+      toggle:
+        icon: material/brightness-auto
+        name: Switch to light mode
+      primary: white
+      accent: red
+
+    # Palette toggle for light mode
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: white
+      accent: red
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+
+    # Palette toggle for dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: red
+      toggle:
+        icon: material/brightness-4
+        name: Switch to system preference
   font:
     text: 'Roboto'
     code: 'Roboto Mono'
@@ -63,4 +86,6 @@ nav:
     - Parameters: parameters.md
     - Rule sets: rule_sets.md
     - Special conditions: special_conditions.md
-    - API Reference: api_reference.md
+    - API Reference: api_reference.md
+extra_css:
+  - assets/css/mkdocs_extra.css
diff --git a/docs/pages/a_simple_example.md b/docs/pages/a_simple_example.md
@@ -15,23 +15,35 @@ Imagine the following use case:
 
 The rules (intentionally simple) are:
 
-!!! success "Admission rules"
-
-    If the applicant has a school authorized power then he is admitted, 
-
-    Else he is not.
-
-!!! example "Course selection rules"
-
-    If he is speaking french and his age is known then he must take the "french" course, 
-
-    Else if his age is unknown (e.g., it's a very old superhero), then he must take the "senior" course,
-
-    Else if he is not speaking french, then he must take the "international" course. 
+``` mermaid
+---
+title: Simple rule set example
+---
+flowchart LR
+    input[fa:fa-mask Super Hero Data ]
+    power{{fa:fa-circle-question Should the hero be admitted?}}
+    admission_true(fa:fa-circle-check Set admission to True)
+    admission_false(fa:fa-circle-xmark Set admission to False)
+    course{{fa:fa-circle-question In which course should the hero be enrolled?}}
+    meal{{fa:fa-circle-question Do we know their favorite meal?}}
+    course_french(fa:fa-cheese French course)
+    course_senior(fa:fa-person-cane Senior course)
+    course_international(fa:fa-globe International course)
+    cook((fa:fa-user-ninja Cook))
+
+
+input --> power
+input --> course
+input --> meal
+power -- Power is flight or strength --> admission_true
+power -- Else --> admission_false
+course -- Age is known and speaks french --> course_french
+course -- Their age is unknown --> course_senior
+course -- Their language is not French --> course_international
+meal -- fa:fa-envelope Send an email to the cook --> cook
 
-!!! info "Send favorite meal rules"
+```
 
-    If he is admitted and has a prefered dish, then we send an email to the school cook with the dish name.
 
 ### Rules
 

diff --git a/docs/pages/assets/css/mkdocs_extra.css b/docs/pages/assets/css/mkdocs_extra.css
@@ -0,0 +1,19 @@
+:root {
+   --md-admonition-icon--beta: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 576 512"><path d="M150.53 371.75h-30.572q6.67-31.313 6.67-56.697v-201.78q0-31.498 5.56-46.877 5.743-15.379 22.049-27.052 16.49-11.858 41.134-11.858 29.274 0 49.1 15.564 20.01 15.379 20.01 43.913 0 33.351-31.684 54.659 47.248 22.234 47.248 69.852 0 25.94-12.599 46.507-12.414 20.381-28.904 29.09-16.304 8.708-39.095 8.708-25.94 0-42.245-19.455v34.463q0 35.576-6.67 60.96zm6.67-112.1q14.452 23.902 40.393 23.902 25.013 0 36.686-18.158 11.673-18.343 11.673-44.469 0-20.011-7.782-40.763-7.597-20.937-19.64-31.869-11.117 2.78-20.011 2.78-18.713 0-18.713-9.821 0-8.894 15.749-8.894 9.82 0 24.458 4.447 13.155-22.234 13.155-48.359 0-23.346-10.376-35.76-10.191-12.414-26.681-12.414-13.155 0-22.604 7.412-9.264 7.411-12.785 17.787-3.523 10.19-3.523 33.537z"/></svg>')
+}
+.md-typeset .admonition.beta,
+.md-typeset details.beta {
+  border-color: #CF363B;
+}
+.md-typeset .beta > .admonition-title,
+.md-typeset .beta > summary {
+  background-color:  #CF363B;
+}
+.md-typeset .beta > .admonition-title::before,
+.md-typeset .beta > summary::before {
+  background-color:  white;
+  -webkit-mask-image: var(--md-admonition-icon--beta);
+          mask-image: var(--md-admonition-icon--beta);
+}
+
+
diff --git a/docs/pages/assets/css/style.css b/docs/pages/assets/css/style.css
@@ -41,8 +41,8 @@ a:hover {
   padding-top: 30px;
 }
 
-.contentN2 .col-md-6 {
-  padding-top: 70px;
+.contentN2 .col-md-4 {
+  padding-top: 40px;
 }
 
 .colDashRight {

diff --git a/docs/pages/how_to.md b/docs/pages/how_to.md
@@ -2,22 +2,22 @@ Ensure that you have correctly installed **Arta** before, check the [Installatio
 
 ## Simple condition
 
-!!! example "Beta feature"
+!!! beta "Beta feature"
 
     **Simple condition** is still a *beta feature*, some cases could not work as designed.
 
 **Simple conditions** are a new and straightforward way of configuring your *conditions*.
 
-It simplifies a lot your rules by:
+It simplifies your rules a lot by:
 
 * Removing the use of a `conditions.py` module (no validation functions needed).
-* Removing the `conditions:` configuration key in your YAML files.
+* Removing the `conditions`: configuration key in your YAML files.
 
 !!! note
 
     With the **simple conditions** you use straight *boolean expressions* directly in your configuration.
 
-    It is easyer to read and maintain :+1:
+    It is easier to read and maintain :+1:
 
 The *configuration key* here is:
 
@@ -59,7 +59,7 @@ How to write a simple condition like:
 * **Left operand (data mapping):** 
     * You must use one of the following prefixes: 
         * `input` (for input data)
-        * `output` (for previous rule's result)
+        * `output` (for the previous rule's result)
     * A *dot path* expression like `input.powers.main_power`.
 * **Operator:** you must use basic python *boolean operator* (i.e., `==, <, >, <=, >=, !=`)
 * **Right operand:** basic python data types (e.i., `str, int, None`).

diff --git a/docs/pages/index.html b/docs/pages/index.html
@@ -36,7 +36,7 @@
     </div>
     <div class="container">
         <div class="row">
-            <div class="col-sm-4 entete sidebar">
+            <div class="col-sm-3 entete sidebar">
                 <div class="sidebar-container">
                     <div class="sidebar-content">
                         <img alt="logo arta" src="assets/img/arta-fond-clair.svg">
@@ -45,36 +45,36 @@
                     </div>
                 </div>
             </div>
-            <div class="col-sm-8 col-sm-offset-4">
+            <div class="col-sm-9 col-sm-offset-3">
                 <div class="row contentN2">
-                    <div class="col-md-6 col-xs-12 colDashRight">
+                    <div class="col-md-8 col-xs-12 colDashRight">
                         <ul class="titleOnLine">
                             <li>An Open Source</li>
                             <li>Rules Engine:</li>
                             <li>Make rule handling simple</li>
                         </ul>
                         <p class="intro">
-                            It's a simple python rules engine designed for python developers.</br></br>
-                            There is one main reason for using <i>Arta</i> and it was the main goal of its development
-                            at <i>MAIF</i>: increase business rules maintainability.
+                            Arta is a simple python rules engine designed for python developers.</br></br>
+                            There is one main reason to use <i>Arta</i> and it was the main goal of its development
+                            at <i>MAIF</i>: <b>increase business rules maintainability</b>.
                             </br>
                             </br>
                             In other words, facilitate rules handling in a python app.
                         </p>
                         <div class="details">
-                            <h1>Features</h1>
+                            <h1>Features:</h1>
                             <ul>
                                 <li>Standardize the definition of a rule. All rules are defined the same way
-                                    in a unique place.</li></br>
-                                <li>Rules are released from the code base, which is less error prone and
+                                    in a single place.</li></br>
+                                <li>Rules are released from the code base, which is less error-prone and
                                     increases clearness.</li></br>
-                                <li>Use <i>Arta</i> whatever your field is.</li></br>
-                                <li>Great combination with Machine Learning: groups all the
-                                    deterministic rules of your ML projects.</li>
+                                <li><i>Arta</i> can be used in your field of application, whichever it is.</li></br>
+                                <li> Mixes well with Machine Learning projects: groups all of your
+                                    deterministic rules.</li>
                             </ul>
                         </div>
                     </div>
-                    <div class="col-md-6 col-xs-12 more-details">
+                    <div class="col-md-4 col-xs-12 more-details">
                         <i class="fa fa-user-o fa-3x" aria-hidden="true"></i>
                         <h2>easy to use</h2>
                         <p>Configure your rules in YAML files</p>
@@ -89,7 +89,7 @@ <h2>Machine Learning</h2>
                         <p>Things are in the right place</p>
                         <p>(deterministic VS probabilistic)</p>
                         <div class="row contentCircle">
-                            <div class="col-md-12 col-xs-4">
+                            <div class="col-md-6 col-xs-4">
                                 <a href="https://github.com/MAIF/arta">
                                     <div class="outer-circle">
                                         <div class="inner-circle">
@@ -98,7 +98,7 @@ <h2>Machine Learning</h2>
                                     </div>
                                 </a>
                             </div>
-                            <div class="col-md-12 col-xs-4">
+                            <div class="col-md-6 col-xs-4">
                                 <a href="./home/">
                                     <div class="outer-circle">
                                         <div class="inner-circle">

diff --git a/docs/pages/rule_sets.md b/docs/pages/rule_sets.md
@@ -126,3 +126,4 @@ classDiagram
     rule "1..*" -- "0..*" condition
     rule "1..*" -- "1" action
 ```
+
diff --git a/docs/pages/special_conditions.md b/docs/pages/special_conditions.md
@@ -35,7 +35,7 @@ if input.name == "john" and input.age == "42":
 
 With the **custom conditions** it's quite simple to implement.
 
-!!! question "Why using a custom condition?"
+!!! question "Why use a custom condition?"
 
     The main goal is to simplify handling of recurrent conditions (e.i., "recurrent" meaning very similar conditions).
 

diff --git a/docs/pages/why.md b/docs/pages/why.md
@@ -1,4 +1,4 @@
-There is one main reason for using **Arta** and it was the main goal of its development: 
+There is one main reason for using **Arta** and it was the main goal behind its development: 
 
 > Increase business rules maintainability.
 
@@ -7,14 +7,14 @@ In other words, facilitate rules handling in a python app.
 
 ## Before Arta :spaghetti:
 
-Rules in code can rapidly become a headache, kind of spaghetti dish of `if`, `elif` and `else` (or even `match/case` since Python 3.10).
+Rules in code can rapidly become a headache for developpers by their evolving into a hellish spaghetti of `if`, `elif` and `else` (or even `match/case` since Python 3.10).
 
 ## After Arta :sparkles:
 
 **Arta** increases rules maintainability:
 
-* By *standardizing* the definition of a rule. All rules are configured or defined the same way in a unique place (or few).
-* Rules are released from the code base, which is *less error prone* and increases clearness.
+* By *standardizing* the definition of a rule. All rules are configured or defined the same way in a single place (or few).
+* Rules are released from the code base, which is *less error-prone* and increases clarity.
 
 !!! example "Improve collaboration"
Original file line number	Diff line number	Diff line change
Expand Up		@@ -126,3 +126,4 @@ classDiagram
		rule "1.." -- "0.." condition
		rule "1..*" -- "1" action
		```