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
2024-04-10 04:51:45 +02:00
parent 2f53638f82
commit c7c18f01cd
11 changed files with 538 additions and 443 deletions
--- a/doc/docs/index.md
+++ b/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
--- a/doc/docs/packages/cmd/katenary.md
+++ b/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.
+
--- a/doc/docs/packages/generator.md
+++ b/doc/docs/packages/generator.md
--- a/doc/docs/packages/generator/extrafiles.md
+++ b/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
-are not objects. Like README.md and notes.txt…
+extrafiles package provides function to generate the Chart files that 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>)
--- a/doc/docs/packages/parser.md
+++ b/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
-dotenv, osenv and profiles.
+Parse compose files and return a project. The project is parsed with dotenv, osenv and profiles.

-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)
--- a/doc/docs/packages/update.md
+++ b/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
-available.
+Update package is used to check if a new version of katenary is available.

 ## Variables

-``` go
-var Version = "master" // reset by cmd/main.go
+<a name="Version"></a>
+
+```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
-the file is executable.
+DownloadFile will download a url to a local file. It also ensure that 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
-propose to download it
+CheckLatestVersion check katenary latest version from release and propose to download it

-Generated by [gomarkdoc](https://github.com/princjef/gomarkdoc)
+Generated by [gomarkdoc](<https://github.com/princjef/gomarkdoc>)
--- a/doc/docs/packages/utils.md
+++ b/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
-defines some constants and functions used in the whole project.
+Utils package provides some utility functions used in katenary. It 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
-const (
-    IconSuccess    Icon = "✅"
-    IconFailure         = "❌"
-    IconWarning         = "⚠️'"
-    IconNote            = "📝"
-    IconWorld           = "🌐"
-    IconPlug            = "🔌"
-    IconPackage         = "📦"
-    IconCabinet         = "🗄️"
-    IconInfo            = "❕"
-    IconSecret          = "🔒"
-    IconConfig          = "🔧"
-    IconDependency      = "🔗"
-)
-```
-
-## func CountStartingSpaces
-
-``` go
+```go
 func CountStartingSpaces(line string) int
 ```

-CountStartingSpaces counts the number of spaces at the beginning of a
-string.
+CountStartingSpaces counts the number of spaces at the beginning of a 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
-array. It returns nil, -1 if not found.
+GetContainerByName returns a container by name and its index in the 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
-name is not found, it returns an empty string.
+GetServiceNameByPort returns the service name for a port. It the service 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
-string. It is used in the templates and defined in \_helper.tpl file.
+TplName returns the name of the kubernetes resource as a template 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
-array.
+GetContainerByName returns a container by name and its index in the 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
-string. You need to check the result.
+WordWrap wraps a string to a given line width. Warning: it may break the 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
-indentation of the src string.
+Wrap wraps a string with a string above and below. It will respect the 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
-respect the indentation of the src string.
+WrapBytes wraps a byte array with a byte array above and below. It will 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
-variable.
+EnvConfig is a struct to hold the description of an environment 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>)
--- a/doc/docs/usage.md
+++ b/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)
- environment variables will be stored in `values.yaml` file
+- if a port is exposed, katenary creates a service (NodePort)
+- 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
-  used by default)
- any other volume (local mount points) are ignored
+- if named volumes are declared, katenary create PersistentVolumeClaims - not enabled in values file
 - `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.
--- a/doc/mkdocs.yml
+++ b/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
--- a/doc/requirements.txt
+++ b/doc/requirements.txt
@@ -1,6 +1,6 @@
-mkdocs>=1.3.0
-Jinja2>=2.10.2
-MarkupSafe>=2.0
-pymdown-extensions>=9.5
-mkdocs-material>=8.3.4
-mkdocs-material-extensions>=1.0.3
+mkdocs>=1.5.3
+Jinja2>=3.1.3
+MarkupSafe>=2.1.5
+pymdown-extensions>=10.7.1
+mkdocs-material>=9.5.17
+mkdocs-material-extensions>=1.3.1