Fixup documentation

- better gomarkdown generation that now fixed the escaped strings, no
  need to use pandoc anymore
- added workflow image
- upgraded versions of mkdocs requirements

Makefile

@@ -4,7 +4,7 @@ VERSION=$(shell git describe --exact-match --tags $(CUR_SHA) 2>/dev/null || echo
 CTN:=$(shell which podman 2>&1 1>/dev/null && echo "podman" || echo "docker")
 PREFIX=~/.local
 
-GOVERSION=1.21
+GOVERSION=1.22
 GO=container
 OUT=katenary
 BLD_CMD=go build -ldflags="-X 'katenary/generator.Version=$(VERSION)'" -o $(OUT)  ./cmd/katenary
@@ -154,6 +154,15 @@ clean:
 	rm -rf katenary dist/* release.id 
 
 
+serve-doc: __label_doc
+	@cd doc && \
+		[ -d venv ] || python -m venv venv; \
+		source venv/bin/activate && \
+		echo "==> Installing requirements in the virtual env..."
+		pip install -qq -r requirements.txt && \
+		echo "==> Serving doc with mkdocs..." && \
+		mkdocs serve
+
 tests: test
 test:
 	@echo -e "\033[1;33mTesting katenary $(VERSION)...\033[0m"
@@ -183,6 +192,8 @@ push-release: build-all
 
 
 __label_doc:
+	@command -v gomarkdoc || (echo "==> We need to install gomarkdoc..." && \
+		go install github.com/princjef/gomarkdoc/cmd/gomarkdoc@latest)
 	@echo "=> Generating labels doc..."
 	# short label doc
 	go run ./cmd/katenary help-labels -m | \
@@ -201,16 +212,6 @@ __label_doc:
 	PACKAGES=$$(for f in $$(find . -name "*.go" -type f); do dirname $$f; done | sort -u)
 	for pack in $$PACKAGES; do
 		echo "-> Generating doc for $$pack"
-		#gomarkdoc -o doc/docs/packages/$$pack.md $$pack
+		gomarkdoc --repository.default-branch $(shell git branch --show-current) -o doc/docs/packages/$$pack.md $$pack
-		gomarkdoc -f azure-devops $$pack | pandoc  -t gfm -o doc/docs/packages/$$pack.md
-		# drop the Index section without removing the title
-		# - remove the Index section, but keep the following heading
 		sed -i  '/^## Index/,/^##/ { /## Index/d; /^##/! d }' doc/docs/packages/$$pack.md
-		# fixes for markdown problem
-		# - there are \* on heading, replace to *
-		sed -i 's/\\\*/\*/g' doc/docs/packages/$$pack.md
-		## parenthis in heading are escaped, replace to unescaped
-		sed -i 's/\\(/\(/g' doc/docs/packages/$$pack.md
-		sed -i 's/\\)/\)/g' doc/docs/packages/$$pack.md
-		## list are badly formatted with 2 spaces, replace to 4
 	done

doc/docs/index.md

@@ -1,20 +1,3 @@
-<style> 
-#logo{ 
-  background-image: url('statics/logo-dark.svg'); 
-  background-repeat: no-repeat; 
-  background-position: center;
-  background-size: contain; 
-  height: 8em; 
-  width: 100%; 
-  margin: 0 auto;
-
-}
-
-[data-md-color-scheme=slate] #logo { 
-  background-image: url('statics/logo-bright.svg'); 
-}
-</style>
-
 <div class="md-center" id="logo"></div>
 
 # Welcome to Katenary documentation
@@ -29,6 +12,11 @@ and Helm Chart creation.
 
 💡 Effortless Efficiency: You only need to add labels when it's necessary to precise things. Then call `katenary convert` and let the magic happen.
 
+<div style="margin: auto" class="zoomable">
+  <img src="statics/workflow.png" id="workflow-image"/>
+</div>
+
+
 # What ?
 
 Katenary is a tool made to help you to transform "compose" files (`docker-compose.yml`, `podman-compose.yml`...) to

doc/docs/packages/cmd/katenary.md

@@ -2,7 +2,11 @@
 
 # katenary
 
-``` go
+```go
 import "katenary/cmd/katenary"
 ```
 
+Katenary CLI, main package.
+
+This package is not intended to be imported. It contains the main function that build the command line with \`cobra\` package.
+

doc/docs/packages/generator/extrafiles.md

@@ -2,27 +2,27 @@
 
 # extrafiles
 
-``` go
+```go
 import "katenary/generator/extrafiles"
 ```
 
-extrafiles package provides function to generate the Chart files that
+extrafiles package provides function to generate the Chart files that are not objects. Like README.md and notes.txt...
-are not objects. Like README.md and notes.txt…
 
-## func NotesFile
+## func [NotesFile](<https://github.com/metal3d/katenary/blob/develop/generator/extrafiles/notes.go#L9>)
 
-``` go
+```go
 func NotesFile() string
 ```
 
 NoteTXTFile returns the content of the note.txt file.
 
-## func ReadMeFile
+<a name="ReadMeFile"></a>
+## func [ReadMeFile](<https://github.com/metal3d/katenary/blob/develop/generator/extrafiles/readme.go#L25>)
 
-``` go
+```go
 func ReadMeFile(charname, description string, values map[string]any) string
 ```
 
 ReadMeFile returns the content of the README.md file.
 
-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

doc/docs/packages/parser.md

@@ -2,19 +2,18 @@
 
 # parser
 
-``` go
+```go
 import "katenary/parser"
 ```
 
-Parser package is a wrapper around compose-go to parse compose files.
+Parser package is a wrapper around compose\-go to parse compose files.
 
-## func Parse
+## func [Parse](<https://github.com/metal3d/katenary/blob/develop/parser/main.go#L10>)
 
-``` go
+```go
 func Parse(profiles []string, dockerComposeFile ...string) (*types.Project, error)
 ```
 
-Parse compose files and return a project. The project is parsed with
+Parse compose files and return a project. The project is parsed with dotenv, osenv and profiles.
-dotenv, osenv and profiles.
 
-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

doc/docs/packages/update.md

@@ -2,54 +2,59 @@
 
 # update
 
-``` go
+```go
 import "katenary/update"
 ```
 
-Update package is used to check if a new version of katenary is
+Update package is used to check if a new version of katenary is available.
-available.
 
 ## Variables
 
-``` go
+<a name="Version"></a>
-var Version = "master" // reset by cmd/main.go
+
+```go
+var (
+    Version = "master" // reset by cmd/main.go
+)
 ```
 
-## func DownloadFile
+<a name="DownloadFile"></a>
+## func [DownloadFile](<https://github.com/metal3d/katenary/blob/develop/update/main.go#L134>)
 
-``` go
+```go
 func DownloadFile(url, exe string) error
 ```
 
-DownloadFile will download a url to a local file. It also ensure that
+DownloadFile will download a url to a local file. It also ensure that the file is executable.
-the file is executable.
 
-## func DownloadLatestVersion
+<a name="DownloadLatestVersion"></a>
+## func [DownloadLatestVersion](<https://github.com/metal3d/katenary/blob/develop/update/main.go#L80>)
 
-``` go
+```go
 func DownloadLatestVersion(assets []Asset) error
 ```
 
 DownloadLatestVersion will download the latest version of katenary.
 
-## type Asset
+<a name="Asset"></a>
+## type [Asset](<https://github.com/metal3d/katenary/blob/develop/update/main.go#L23-L26>)
 
 Asset is a github asset from release url.
 
-``` go
+```go
 type Asset struct {
     Name string `json:"name"`
     URL  string `json:"browser_download_url"`
 }
 ```
 
-### func CheckLatestVersion
+<a name="CheckLatestVersion"></a>
+### func [CheckLatestVersion](<https://github.com/metal3d/katenary/blob/develop/update/main.go#L29>)
 
-``` go
+```go
 func CheckLatestVersion() (string, []Asset, error)
 ```
 
-CheckLatestVersion check katenary latest version from release and
+CheckLatestVersion check katenary latest version from release and propose to download it
-propose to download it
 
-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

doc/docs/packages/utils.md

@@ -2,186 +2,193 @@
 
 # utils
 
-``` go
+```go
 import "katenary/utils"
 ```
 
-Utils package provides some utility functions used in katenary. It
+Utils package provides some utility functions used in katenary. It defines some constants and functions used in the whole project.
-defines some constants and functions used in the whole project.
 
-## Constants
+## func [CountStartingSpaces](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L31>)
 
-Icons used in katenary.
+```go
-
-``` go
-const (
-    IconSuccess    Icon = "✅"
-    IconFailure         = "❌"
-    IconWarning         = "⚠️'"
-    IconNote            = "📝"
-    IconWorld           = "🌐"
-    IconPlug            = "🔌"
-    IconPackage         = "📦"
-    IconCabinet         = "🗄️"
-    IconInfo            = "❕"
-    IconSecret          = "🔒"
-    IconConfig          = "🔧"
-    IconDependency      = "🔗"
-)
-```
-
-## func CountStartingSpaces
-
-``` go
 func CountStartingSpaces(line string) int
 ```
 
-CountStartingSpaces counts the number of spaces at the beginning of a
+CountStartingSpaces counts the number of spaces at the beginning of a string.
-string.
 
-## func GetContainerByName
+<a name="GetContainerByName"></a>
+## func [GetContainerByName](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L82>)
 
-``` go
+```go
 func GetContainerByName(name string, containers []corev1.Container) (*corev1.Container, int)
 ```
 
-GetContainerByName returns a container by name and its index in the
+GetContainerByName returns a container by name and its index in the array. It returns nil, \-1 if not found.
-array. It returns nil, -1 if not found.
 
-## func GetKind
+<a name="GetKind"></a>
+## func [GetKind](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L44>)
 
-``` go
+```go
 func GetKind(path string) (kind string)
 ```
 
 GetKind returns the kind of the resource from the file path.
 
-## func GetServiceNameByPort
+<a name="GetServiceNameByPort"></a>
+## func [GetServiceNameByPort](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L72>)
 
-``` go
+```go
 func GetServiceNameByPort(port int) string
 ```
 
-GetServiceNameByPort returns the service name for a port. It the service
+GetServiceNameByPort returns the service name for a port. It the service name is not found, it returns an empty string.
-name is not found, it returns an empty string.
 
-## func GetValuesFromLabel
+<a name="GetValuesFromLabel"></a>
+## func [GetValuesFromLabel](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L122>)
 
-``` go
+```go
 func GetValuesFromLabel(service types.ServiceConfig, LabelValues string) map[string]*EnvConfig
 ```
 
 GetValuesFromLabel returns a map of values from a label.
 
-## func HashComposefiles
+<a name="HashComposefiles"></a>
+## func [HashComposefiles](<https://github.com/metal3d/katenary/blob/develop/utils/hash.go#L12>)
 
-``` go
+```go
 func HashComposefiles(files []string) (string, error)
 ```
 
 HashComposefiles returns a hash of the compose files.
 
-## func Int32Ptr
+<a name="Int32Ptr"></a>
+## func [Int32Ptr](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L25>)
 
-``` go
+```go
 func Int32Ptr(i int32) *int32
 ```
 
 Int32Ptr returns a pointer to an int32.
 
-## func MapKeys
+<a name="MapKeys"></a>
+## func [MapKeys](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L156>)
 
-``` go
+```go
 func MapKeys(m map[string]interface{}) []string
 ```
 
-## func PathToName
 
-``` go
+
+<a name="PathToName"></a>
+## func [PathToName](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L101>)
+
+```go
 func PathToName(path string) string
 ```
 
 PathToName converts a path to a kubernetes complient name.
 
-## func StrPtr
+<a name="StrPtr"></a>
+## func [StrPtr](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L28>)
 
-``` go
+```go
 func StrPtr(s string) *string
 ```
 
 StrPtr returns a pointer to a string.
 
-## func TplName
+<a name="TplName"></a>
+## func [TplName](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L17>)
 
-``` go
+```go
 func TplName(serviceName, appname string, suffix ...string) string
 ```
 
-TplName returns the name of the kubernetes resource as a template
+TplName returns the name of the kubernetes resource as a template string. It is used in the templates and defined in \_helper.tpl file.
-string. It is used in the templates and defined in \_helper.tpl file.
 
-## func TplValue
+<a name="TplValue"></a>
+## func [TplValue](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L92>)
 
-``` go
+```go
 func TplValue(serviceName, variable string, pipes ...string) string
 ```
 
-GetContainerByName returns a container by name and its index in the
+GetContainerByName returns a container by name and its index in the array.
-array.
 
-## func Warn
+<a name="Warn"></a>
+## func [Warn](<https://github.com/metal3d/katenary/blob/develop/utils/icons.go#L25>)
 
-``` go
+```go
 func Warn(msg ...interface{})
 ```
 
 Warn prints a warning message
 
-## func WordWrap
+<a name="WordWrap"></a>
+## func [WordWrap](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L152>)
 
-``` go
+```go
 func WordWrap(text string, lineWidth int) string
 ```
 
-WordWrap wraps a string to a given line width. Warning: it may break the
+WordWrap wraps a string to a given line width. Warning: it may break the string. You need to check the result.
-string. You need to check the result.
 
-## func Wrap
+<a name="Wrap"></a>
+## func [Wrap](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L61>)
 
-``` go
+```go
 func Wrap(src, above, below string) string
 ```
 
-Wrap wraps a string with a string above and below. It will respect the
+Wrap wraps a string with a string above and below. It will respect the indentation of the src string.
-indentation of the src string.
 
-## func WrapBytes
+<a name="WrapBytes"></a>
+## func [WrapBytes](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L67>)
 
-``` go
+```go
 func WrapBytes(src, above, below []byte) []byte
 ```
 
-WrapBytes wraps a byte array with a byte array above and below. It will
+WrapBytes wraps a byte array with a byte array above and below. It will respect the indentation of the src string.
-respect the indentation of the src string.
 
-## type EnvConfig
+<a name="EnvConfig"></a>
+## type [EnvConfig](<https://github.com/metal3d/katenary/blob/develop/utils/utils.go#L116-L119>)
 
-EnvConfig is a struct to hold the description of an environment
+EnvConfig is a struct to hold the description of an environment variable.
-variable.
 
-``` go
+```go
 type EnvConfig struct {
     Description string
     Service     types.ServiceConfig
 }
 ```
 
-## type Icon
+<a name="Icon"></a>
+## type [Icon](<https://github.com/metal3d/katenary/blob/develop/utils/icons.go#L6>)
 
 Icon is a unicode icon
 
-``` go
+```go
 type Icon string
 ```
 
-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+<a name="IconSuccess"></a>Icons used in katenary.
+
+```go
+const (
+    IconSuccess    Icon = "✅"
+    IconFailure    Icon = "❌"
+    IconWarning    Icon = "⚠️'"
+    IconNote       Icon = "📝"
+    IconWorld      Icon = "🌐"
+    IconPlug       Icon = "🔌"
+    IconPackage    Icon = "📦"
+    IconCabinet    Icon = "🗄️"
+    IconInfo       Icon = "❕"
+    IconSecret     Icon = "🔒"
+    IconConfig     Icon = "🔧"
+    IconDependency Icon = "🔗"
+)
+```
+
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)

doc/docs/usage.md

@@ -4,24 +4,56 @@ Basically, you can use `katenary` to transpose a docker-compose file (or any com
 `podman-compose` and `docker-compose`) to a configurable Helm Chart. This resulting helm chart can be installed with
 `helm` command to your Kubernetes cluster.
 
+!!! Warning "YAML in multiline label" 
+    
+    Compose only accept text label. So, to put a complete YAML content in the target label, you need to use a pipe char (`|` or `|-`) 
+    and to **indent** your content.
+
+    For example :
+
+    ```yaml
+      labels:
+        # your labels
+        foo: bar
+        # katenary labels with multiline
+        katenary.v3/ingress: |-
+          hostname: my.website.tld
+          port: 80
+        katenary.v3/ports: |-
+          - 1234
+    ```
+
+
 Katenary transforms compose services this way:
 
 - Takes the service and create a "Deployment" file
 - if a port is declared, katenary creates a service (ClusterIP)
-- it a port is exposed, katenary creates a service (NodePort)
+- if a port is exposed, katenary creates a service (NodePort)
-- environment variables will be stored in `values.yaml` file
+- environment variables will be stored inside a configMap
 - image, tags, and ingresses configuration are also stored in `values.yaml` file
-- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file (a `emptyDir` is
+- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file
-  used by default)
-- any other volume (local mount points) are ignored
 - `depends_on` needs that the pointed service declared a port. If not, you can use labels to inform katenary
 
+For any other specific configuration, like binding local files as configMap, bind variables, add values with documentation, etc. You'll need to use labels.
+
 Katenary can also configure containers grouping in pods, declare dependencies, ignore some services, force variables as
 secrets, mount files as `configMap`, and many others things. To adapt the helm chart generation, you will need to use
 some specific labels.
 
 For more complete label usage, see [the labels page](labels.md).
 
+!!! Info "Overriding file"
+
+    It could be sometimes more convinient to separate the 
+    configuration related to Katenary inside a secondary file.
+
+    Instead of adding labels inside the `compose.yaml` file,
+    you can create a file named `compose.katenary.yaml` and 
+    declare your labels inside. Katenary will detect it by 
+    default. 
+
+    **No need to precise the file in the command line.**
+
 ## Make convertion
 
 After having installed `katenary`, the standard usage is to call:
@@ -153,8 +185,6 @@ services:
       image: mariadb
 ```
 
-!!! Warning This is a "multiline" label that accepts YAML or JSON content, don't forget to add a pipe char (`|` or `|-`)
-and to **indent** your content
 
 This label can be used to map others environment for any others reason. E.g. to change an informational environment
 variable.

doc/mkdocs.yml

@@ -42,6 +42,7 @@ nav:
     - coding.md
     - dependencies.md
   - Go Packages:
+    - packages/cmd/katenary.md
     - packages/generator.md
     - packages/parser.md
     - packages/update.md

doc/requirements.txt

@@ -1,6 +1,6 @@
-mkdocs>=1.3.0
+mkdocs>=1.5.3
-Jinja2>=2.10.2
+Jinja2>=3.1.3
-MarkupSafe>=2.0
+MarkupSafe>=2.1.5
-pymdown-extensions>=9.5
+pymdown-extensions>=10.7.1
-mkdocs-material>=8.3.4
+mkdocs-material>=9.5.17
-mkdocs-material-extensions>=1.0.3
+mkdocs-material-extensions>=1.3.1