Enhance documentation

- upgraded mkdocs and dependencise (+ add mermaid)
- linted markdown
- add more details

Author: metal3d

doc/docs/coding.md

@@ -9,7 +9,7 @@ Katenary is developed in Go. The version currently supported is 1.20. For reason
 preferred to `interface{}`.
 
 Since version v3, Katenary uses, in addition to `go-compose`, the `k8s` library to generate objects that are guaranteed
-to work before transformation. Katenary adds Helm syntax entries to add loops, transformations and conditions.
+to work before transformation. Katenary adds Helm syntax entries to add loops, transformations, and conditions.
 
 We really try to follow best practices and code principles. But, Katenary needs a lot of workarounds and string
 manipulation during the process. There are, also, some drawbacks using standard k8s packages that makes a lot of type
@@ -25,6 +25,35 @@ During conversion, the `generator` package is primarily responsible for creating
 one `Deployment` per `compose` service. If the container coming from "compose" exposes ports (explicitly), then a
 service is created.
 
+```mermaid
+flowchart TD
+
+    D[Deployment]:::outputs@{shape: curv-trap}
+    C[Container List]@{shape: docs}
+    ConfigMap:::outputs@{shape: curv-trap}
+    Secrets:::outputs@{shape: curv-trap}
+    H[Helm Chart.yaml file]:::outputs@{shape: curv-trap}
+    Val[Values files]:::outputs@{shape: curv-trap}
+    PVC:::outputs@{shape: curv-trap}
+    S[Service]:::outputs@{shape: curv-trap}
+    
+    A[Compose file]:::inputs --> B[Compose parser]
+    B --> G[Generator]
+    G --> P[Ports exposed to services] ---> S
+    G ------> H
+    G --> C --> D
+    G ------> Val
+    G ....-> M[Merge Continainers if same-pod] 
+    M ..-> C
+    G --> E[Environment variables] ----> Secrets & ConfigMap
+    G--> V[Bind volumes] -------> PVC
+    V -----> CF[ Create ConfigMap\nfor static files as\nconfigmap-files] --> ConfigMap
+
+    Secrets & ConfigMap -- create envFrom --> D
+    V -- bind volumes --> D
+    
+```
+
 If the declaration of a container is to be integrated into another pod (via the `same-pod` label), this `Deployment` and
 its associated service are still created. They are deleted last, once the merge has been completed.
 
@@ -34,7 +63,6 @@ The `generator` package is where object struct are defined, and where the `Gener
 
 The generation is made by using a `HelmChart` object:
 
-```golang
 ```golang
 for _, service := range project.Services {
     dep := NewDeployment(service)
@@ -44,6 +72,7 @@ for _, service := range project.Services {
         Servicename: service.Name,
     }
 }
+```
 
 **A lot** of string manipulations are made by each `Yaml()` methods. This is where you find the complex and impacting
 operations. The `Yaml` methods **don't return a valid YAML content**. This is a Helm Chart Yaml content with template

doc/docs/dependencies.md

@@ -2,15 +2,17 @@
 
 Katenary uses `compose-go` and several kubernetes official packages.
 
-- `github.com/compose-spec/compose-go`: to parse compose files. It ensures that:
-    - the project respects the "compose" specification
-    - katenary uses the "compose" struct exactly the same way that podman-compose or docker does
+- `github.com/compose-spec/compose-go`: to parse compose files. It ensures :
+    - that the project respects the "compose" specification
+    - that Katenary uses the "compose" struct exactly the same way  `podman compose` or `docker copose` does
 - `github.com/spf13/cobra`: to parse command line arguments, subcommands and flags. It also generates completion for
-  bash, zsh, fish and powershell.
+  bash, zsh, fish and PowerShell.
 - `github.com/thediveo/netdb`: to get the standard names of a service from its port number
 - `gopkg.in/yaml.v3`:
     - to generate `Chart.yaml` and `values.yaml` files (only)
     - to parse Katenary labels in the compose file
 - `k8s.io/api` and `k8s.io/apimachinery` to create Kubernetes objects
-- `sigs.k8s.io/yaml`: to generate Katenary yaml files
+- `sigs.k8s.io/yaml`: to generate Katenary YAML files in the format of Kubernetes objects
 
+There are also some other packages used in the project, like `gopkg.in/yaml` to parse labels. I'm sorry to not list the
+entire dependencies. You can check the `go.mod` file to see all the dependencies.

doc/docs/faq.md

@@ -2,86 +2,108 @@
 
 ## Why Katenary?
 
-The main author[^1] of Katenary is a big fan of Podman, Docker and makes a huge use of Compose. He uses it a lot in his daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose. He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts.
+The main author[^1] of Katenary is a big fan of Podman, Docker and makes a huge use of Compose. He uses it a lot in his
+daily work. When he started to work with Kubernetes, he wanted to have the same experience as with Docker Compose.
+He wanted to have a tool that could convert his `docker-compose` files to Kubernetes manifests, but also to Helm charts.
 
-Kompose was a good option. But the lacks of some options and configuration for the output Helm chart made him think about creating a new tool. He wanted to have a tool that could generate a complete Helm chart, with a lot of options and flexibility.
+Kompose was a good option. But the lacks of some options and configuration for the output Helm chart made him think
+about creating a new tool. He wanted to have a tool that could generate a complete Helm chart, with a lot of options
+and flexibility.
 
-[^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka metal3d, Tech Lead and DevOps Engineer at Klee Group.
+[^1]: I'm talking about myself :sunglasses: - Patrice FERLET, aka Metal3d, Tech Lead and DevOps Engineer at Klee Group.
 
 ## What's the difference between Katenary and Kompose?
 
-[Kompose](https://kompose.io/) is a very nice tool, made by the Kubernetes community. It's a tool to convert `docker-compose` files to Kubernetes manifests. It's a very good tool, and it's more mature than Katenary.
+[Kompose](https://kompose.io/) is a very nice tool, made by the Kubernetes community. It's a tool to convert
+`docker-compose` files to Kubernetes manifests. It's a very good tool, and it's more mature than Katenary.
 
-Kompose is able to genererate Helm charts, but [it could be not the case in future releases](https://github.com/kubernetes/kompose/issues/1716) for several reasons[^2].
+Kompose is able to generate Helm charts, but [it could be not the case in future releases](https://github.com/kubernetes/kompose/issues/1716) for several reasons[^2].
 
-[^2]: The author of Kompose explains that they have no bandwidth to maintain the Helm chart generation. It's a complex task, and we can confirm. Katenary takes a lot of time to be developed and maintained. This issue mentions Katenary as an alternative to Helm chart generation :smile:
+[^2]: The author of Kompose explains that they have no bandwidth to maintain the Helm chart generation. It's a complex
+task, and we can confirm. Katenary takes a lot of time to be developed and maintained. This issue mentions Katenary as
+an alternative to Helm chart generation :smile:
 
-The project is focused on Kubernetes manifests and proposes to use "kusomize" to adapt the manifests. Helm seems to be not the priority.
+The project is focused on Kubernetes manifests and proposes to use "kusomize" to adapt the manifests. Helm seems to be
+not the priority.
 
-Anyway, before this decision, the Helm chart generation was not what we expected. We wanted to have a more complete chart, with more options and more flexibility. 
+Anyway, before this decision, the Helm chart generation was not what we expected. We wanted to have a more complete
+chart, with more options and more flexibility.
 
 > That's why we decided to create Katenary.
 
-Kompose didn't manage to generate a values file, complexe volume binding, and many other things. It was also not able to manage dependencies between services.
+Kompose didn't manage to generate a values file, complex volume binding, and many other things. It was also not able
+to manage dependencies between services.
 
 > Be sure that we don't want to compete with Kompose. We just want to propose a different approach to the problem.
 
-Kompose is an excellent tool, and we use it in some projects. It's a good choice if you want to convert your `docker-compose` files to Kubernetes manifests, but if you want to use Helm, Katenary is the tool you need.
+Kompose is an excellent tool, and we use it in some projects. It's a good choice if you want to convert
+your `docker-compose` files to Kubernetes manifests, but if you want to use Helm, Katenary is the tool you need.
 
 ## Why not using "one label" for all the configuration?
 
-That was a dicsussion I had with my colleagues. The idea was to use a single label to store all the configuration. But, it's not a good idea.
+That was a dicsussion I had with my colleagues. The idea was to use a single label to store all the configuration.
+But, it's not a good idea.
 
-Sometimes, you will have a long list of things to configure, like ports, ingress, dependecies, etc. It's better to have a clear and readable configuration. Segmented labels are easier to read and to maintain. It also avoids to have too many indentation levels in the YAML file.
+Sometimes, you will have a long list of things to configure, like ports, ingress, dependencies, etc. It's better to have
+a clear and readable configuration. Segmented labels are easier to read and to maintain. It also avoids having too
+many indentation levels in the YAML file.
 
 It is also more flexible. You can add or remove labels without changing the others.
 
 ## Why not using a configuration file?
 
-The idea was to keep the configuration at a same place, and using the go-compose library to read the labels. It's easier to have a single file to manage.
+The idea was to keep the configuration at a same place, and using the go-compose library to read the labels. It's
+easier to have a single file to manage.
 
-By the way, Katenary auto accepts a `compose.katenary.yaml` file in the same directory. It's a way to separate the configuration from the compose file. It uses the [overrides mecanism](https://docs.docker.com/compose/multiple-compose-files/merge/) like "compose" does.
+By the way, Katenary auto accepts a `compose.katenary.yaml` file in the same directory. It's a way to separate the
+configuration from the compose file. It uses
+the [overrides' mechanism](https://docs.docker.com/compose/multiple-compose-files/merge/) like "compose" does.
 
-
-## Why not developping with Rust?
+## Why not developing with Rust?
 
 Seriously...
 
 OK, I will answer.
 
-Rust is a good language. But, Podman, Docker, Kubernetes, Helm, and mostly all technologies around Kubernetes are written in Go. We have a large ecosystem in Go to manipulate, read, and write Kubernetes manifests as parsing Compose files.
+Rust is a good language. But, Podman, Docker, Kubernetes, Helm, and mostly all technologies around Kubernetes are
+written in Go. We have a large ecosystem in Go to manipulate, read, and write Kubernetes manifests as parsing
+Compose files.
 
-Go is better for this task.
+> Go is better for this task.
 
 There is no reason to use Rust for this project.
 
 ## Any chance to have a GUI?
 
-Yes, it's a possibility. But, it's not a priority. We have a lot of things to do before. We need to stabilize the project, to have a good documentation, to have a good test coverage, and to have a good community.
+Yes, it's a possibility. But, it's not a priority. We have a lot of things to do before. We need to stabilize the
+project, to have a good documentation, to have a good test coverage, and to have a good community.
 
 But, in a not so far future, we could have a GUI. The choice of [Fyne.io](https://fyne.io) is already made and we tested some concepts.
 
-
 ## I'm rich (or not), I want to help you. How can I do?
 
 You can help us in many ways.
 
-- The first things we really need, more than money, more than anything else, is to have feedback. If you use Katenary, if you have some issues, if you have some ideas, please open an issue on the [GitHub repository](https://github.com/metal3d/katenary).
-- The second things is to help us to fix issues. If you're a Go developper, or if you want to fix the documentation, your help is greatly appreciated.
+- The first things we really need, more than money, more than anything else, is to have feedback. If you use Katenary,
+if you have some issues, if you have some ideas, please open an issue on the [GitHub repository](https://github.com/metal3d/katenary).
+- The second things is to help us to fix issues. If you're a Go developper, or if you want to fix the documentation,
+your help is greatly appreciated.
 - And then, of course, we need money, or sponsors.
 
 ### If you're a company
 
-We will be happy to communicate your help by putting your logo on the website and in the documentaiton. You can sponsor us by giving us some money, or by giving us some time of your developers, or leaving us some time to work on the project.
+We will be happy to communicate your help by putting your logo on the website and in the documentaiton. You can sponsor
+us by giving us some money, or by giving us some time of your developers, or leaving us some time to work on the project.
 
 ### If you're an individual
 
-All donators will be listed on the website and in the documentation. You can give us some money by using the [GitHub Sponsors]()
+All donators will be listed on the website and in the documentation. You can give us some money by using
+the [GitHub Sponsors]()
 
-All main contributors[^3] will be listed on the website and in the documentation. 
+All main contributors[^3] will be listed on the website and in the documentation.
 
 > If you want to be anonymous, please tell us.
 
-
-[^3]: Main contributors are the people who have made a significant contribution to the project. It could be code, documentation, or any other help. There is no defined rules, at this time, to evaluate the contribution. It's a subjective decision.
-
+[^3]: Main contributors are the people who have made a significant contribution to the project. It could be code,
+documentation, or any other help. There is no defined rules, at this time, to evaluate the contribution.
+It's a subjective decision.

doc/docs/index.md

@@ -6,10 +6,10 @@
 
 🚀 Unleash Productivity with Katenary! 🚀
 
-Tired of manual conversions? Katenary harnesses the labels from your "compose" file to craft complete Helm Charts 
+Tired of manual conversions? Katenary harnesses the labels from your "compose" file to craft complete Helm Charts
 effortlessly, saving you time and energy.
 
-🛠️ Simple autmated CLI: Katenary handles the grunt work, generating everything needed for seamless service binding 
+🛠️ Simple autmated CLI: Katenary handles the grunt work, generating everything needed for seamless service binding
 and Helm Chart creation.
 
 💡 Effortless Efficiency: You only need to add labels when it's necessary to precise things. Then call `katenary convert`
@@ -19,13 +19,12 @@ and let the magic happen.
 ![](statics/workflow.svg)
 </div>
 
-
 # What is it?
 
 Katenary is a tool made to help you to transform "compose" files (`compose.yaml`, `docker-compose.yml`, `podman-compose.yml`...) to
 complete and production ready [Helm Chart](https://helm.sh).
 
-You'll be able to deploy your project in [:material-kubernetes: Kubernetes](https://kubernetes.io) in a few seconds 
+You'll be able to deploy your project in [:material-kubernetes: Kubernetes](https://kubernetes.io) in a few seconds
 (of course, more if you need to tweak with labels).
 
 It uses your current file and optionnaly labels to configure the result.
@@ -42,19 +41,19 @@ share it with the community.
 
 The main developer is [Patrice FERLET](https://github.com/metal3d).
 
-The project source 
+The project source
 code is hosted on the [:fontawesome-brands-github: Katenary GitHub Repository](https://github.com/metal3d/katenary).
 
 ## Install Katenary
 
-Katenary is developped using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language. 
+Katenary is developped using the :fontawesome-brands-golang:{ .gopher } [Go](https://go.dev) language.
 The binary is statically linked, so you can simply download it from the [release
 page](https://github.com/metal3d/katenary/releases) of the project in GutHub.
 
-You need to select the right binary for your operating system and architecture, and copy the binary in a directory 
+You need to select the right binary for your operating system and architecture, and copy the binary in a directory
 that is in your `PATH`.
 
-If you are a Linux user, you can use the "one line installation command" which will download the binary in your 
+If you are a Linux user, you can use the "one line installation command" which will download the binary in your
 `$HOME/.local/bin` directory if it exists.
 
 ```bash
@@ -66,10 +65,9 @@ sh <(curl -sSL https://raw.githubusercontent.com/metal3d/katenary/master/install
 
     Of course, you need to install Katenary once :smile:
 
-
 !!! Note "You prefer to compile it, no need to install Go"
-    You can also build and install it yourself, the provided Makefile has got a `build` command that uses `podman` or 
-    `docker` to build the binary. 
+    You can also build and install it yourself, the provided Makefile has got a `build` command that uses `podman` or
+    `docker` to build the binary.
 
     So, you don't need to install Go compiler :+1:.
 
@@ -85,7 +83,7 @@ make build
 make install
 ```
 
-`make install` copies `./katenary` binary to your user binary path (`~/.local/bin`) 
+`make install` copies `./katenary` binary to your user binary path (`~/.local/bin`)
 
 You can install it in other directory by changing the `PREFIX` variable. E.g.:
 
@@ -109,8 +107,7 @@ source <(katenary completion bash)
 
 Add this line in you `~/.profile`, `~/.bash_aliases` or `~/.bashrc` file to have completion at startup.
 
-
-## What a name...
+## What a name
 
 A catenary is the curve that a hanging chain or cable assumes under its own weight when supported only at its ends.
 I, the maintainer, decided to name "Katenary" this project because it's like a chain that links a boat to a dock.
@@ -122,14 +119,13 @@ Anyway, it's too late to change the name now :smile:
 
     I spent time to find it :wink:
 
-## Special thanks to...
+## Special thanks to
 
 I really want to thank all the contributors, testers, and of course, the authors of the packages and tools that are used
 in this project. There is too many to list here. Katenary can works because of all these people. Open source is a great
 thing! :heart:
 
-
-!!! Edit "Special thanks" 
+!!! Edit "Special thanks"
 
     **Katenary is built with:** <br />