Merge branch 'develop'

docs/learning/mkdocs_tutorial/deploy.en.md

@@ -0,0 +1,40 @@
+---
+title: Deployment
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+Once we have completed the content of our site and tested its functionality locally, we need to make it visible to everyone for accessibility. To do this, we have several options:
+
+## GitHub Pages
+
+1. Host your MkDocs project on GitHub.
+2. Use the `mkdocs gh-deploy` command to build your documentation and upload it to the `gh-pages` branch of your GitHub repository.
+3. Your documentation will be automatically hosted on GitHub Pages at the address `https://username.github.io/repository`.
+
+## Netlify
+
+1. Connect your MkDocs project to a repository on a service like GitHub.
+2. Create a Netlify account and a new site, linking it to your repository.
+3. Configure the build settings in Netlify to run the `mkdocs build` command during the build process.
+4. Netlify will automatically publish and host your MkDocs site.
+
+## Read the Docs
+
+1. If your project is open source, you can use Read the Docs to automatically build and host your MkDocs documentation.
+2. Connect your project's repository to Read the Docs and configure the build settings.
+3. Every time you make changes in your repository, Read the Docs will automatically build and update your documentation.
+
+## Manual Deployment
+
+1. Build your MkDocs documentation using the `mkdocs build` command.
+2. Copy the generated files from the `site` directory to your web server.
+3. Configure your web server to serve the static files. For example, if you are using Apache or Nginx, configure a virtual host to point to the documentation directory.
+
+## Docker
+
+1. Build a Docker image containing your MkDocs documentation.
+2. Upload the Docker image to a container registry like Docker Hub.
+3. Deploy the Docker image on a container orchestration platform such as Kubernetes or Docker Swarm.

docs/learning/mkdocs_tutorial/deploy.md

@@ -0,0 +1,41 @@
+---
+title: Deploy
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+Una volta che abbiamo completato il contenuto del nostro sito e abbiamo testato il suo funzionamento in locale dobbiamo renderlo visibile a tutti perchè sia consultabile.
+Per fare ciò abbiamo diverse possibilità:
+
+## GitHub Pages
+
+1. Ospita il tuo progetto MkDocs su GitHub.
+2. Usa il comando mkdocs gh-deploy per costruire la tua documentazione e caricarla sul ramo gh-pages del tuo repository GitHub.
+3. La tua documentazione sarà automaticamente ospitata su GitHub Pages all'indirizzo https://username.github.io.repository
+
+## Netlify
+
+1. Collega il tuo progetto MkDocs a un repository su un servizio come GitHub.
+2. Crea un account Netlify e crea un nuovo sito, collegandolo al tuo repository
+3. Configura le impostazioni di compilazione in Netlify per eseguire il comando mkdocs build durante il processo di compilazione.
+4. Netlify pubblicherà e ospiterà automaticamente il tuo sito MkDocs.
+
+## Read the Docs
+
+1. Se il tuo progetto è open source, puoi utilizzare Read the Docs per compilare e ospitare automaticamente la tua documentazione MkDocs.
+2. Collega il repository del tuo progetto a Read the Docs e configura le impostazioni di compilazione.
+3. Ogni volta che effettui modifiche nel tuo repository, Read the Docs compilerà automaticamente e aggiornerà la tua documentazione.
+
+## Pubblicazione Manuale
+
+1. Costruisci la tua documentazione MkDocs usando il comando mkdocs build.
+2. Copia i file generati dalla directory site sul tuo server web.
+3. Configura il tuo server web per servire i file statici. Ad esempio, se stai utilizzando Apache o Nginx, configura un virtual host per puntare alla directory della documentazione.
+
+## Docker
+
+1. Costruisci un'immagine Docker contenente la tua documentazione MkDocs.
+2. Carica l'immagine Docker in un registro dei container come Docker Hub.
+3. Distribuisci l'immagine Docker su una piattaforma di orchestrazione dei container come Kubernetes o Docker Swarm.

docs/learning/mkdocs_tutorial/document_code.en.md

@@ -0,0 +1,72 @@
+---
+title: Documenting code
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+As we have seen mkdocs is very convenient and fast, one of the most used features of the library is to quickly comment and share technical documentation related to code.
+
+To do this you need to use a [particular extension](https://mkdocstrings.github.io/) called `mkdocstring`.
+
+This extension allows you to automatically create documentation of Python functions and classes, being able to read notations and `docstrings` by turning them into HTML code.
+
+Be careful in installing the library which is called: `mkdocstrings-python` and not just `mkdocstrings`, you must therefore do with poetry:
+
+`poetry add mkdocstrings-python`.
+
+The difference is that `mkdocstrings-python` is the handler to support python code.
+
+With mkdocstrings you can also document and support `shell` code by installing: `mkdocstrings-shell`
+
+Once the library is installed you will also need to configure it, to do this it is important to put in the `mkdocs.yaml` file within the `plugins` section this configuration
+
+```yaml
+ - mkdocstrings:
+          default_handler: python
+          handlers:
+              python:
+                  options:
+                      show_source: true
+                      show_root_heading: yes
+                      heading_level: 0
+                      filters:
+                          - '!^_' # exclude all members starting with _
+                          - '!^__init__$' # exclude __init__ modules and methods
+
+```
+
+To do this try creating a function, for example:
+
+```python
+
+def sum_numbers(num1: int, num2: int) -> int:
+    ```
+    def sum_numbers(num1: int, num2: int) -> int:
+    """Sum 2 int numbers and obtain a result
+
+    Args:
+        num1 (int): the first number you want to sum
+        num2 (int): the second number you want to sum
+
+    Returns:
+        result (int): the sum of the two numbers
+    """
+    return num1 + num2
+
+```
+
+After that you will have to import the package inside a markdown file using a special notation, suppose your code is in the following folder (or module): `myapp/test/utils.py`
+
+Inside a markdown file you will need to write:
+
+```markdown
+
+::: myapp.test.utils.sum_numbers
+
+```
+
+Automatically mkdocstring will display within the site your example.
+
+Of course we always recommend that you try to edit markdown files and always check the result, you can always make sure to add more comments or embellishments in markdown normally.

docs/learning/mkdocs_tutorial/document_code.md

@@ -0,0 +1,72 @@
+---
+title: Documentare il codice
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+Come abbiamo visto mkdocs è molto comodo e veloce, una delle funzionalità più utilizzate della libreria è per commentare e condividere velocemente documentazione tecnica relativa al codice.
+
+Per farlo è necessario utilizzare una [particolare estensione](https://mkdocstrings.github.io/) chiamata `mkdocstring`.
+
+Questa estensione consente di creare automaticamente la documentazione delle funzioni e delle classi Python, riuscendo a leggedere le notazioni e le `docstring` trasformandole in codice HTML.
+
+Attenzione nell'installazione della libreria che si chiama: `mkdocstrings-python` e non solamente `mkdocstrings`, dovete quindi fare con poetry:
+
+`poetry add mkdocstrings-python`
+
+La differenza è che `mkdocstrings-python` è l'handler per supportare il codice python.
+
+Con mkdocstrings è anche possibile documentare e supportare codice `shell` installando: `mkdocstrings-shell`
+
+Una volta installata la libreria sarà necessario anche configurarla, per farlo è importante inserire nel `mkdocs.yaml` file all'interno della sezione `plugins` questa configurazione
+
+```yaml
+ - mkdocstrings:
+          default_handler: python
+          handlers:
+              python:
+                  options:
+                      show_source: true
+                      show_root_heading: yes
+                      heading_level: 0
+                      filters:
+                          - '!^_'             # exclude all members starting with _
+                          - '!^__init__$'             # exclude __init__ modules and methods
+
+```
+
+Per farlo prova a creare una funzione, ad esempio:
+
+```python
+
+def sum_numbers(num1: int, num2: int) -> int:
+    ```
+    def sum_numbers(num1: int, num2: int) -> int:
+    """Sum 2 int numbers and obtain a result
+
+    Args:
+        num1 (int): the first number you want to sum
+        num2 (int): the second number you want to sum
+
+    Returns:
+        result (int): the sum of the two numbers
+    """
+    return num1 + num2
+
+```
+
+Dopodiche dovrai importare il package all'interno di un file markdown utilizzando una speciale notazione, supponiamo che il tuo codice sia nella seguente cartella (o modulo): `myapp/test/utils.py`
+
+All'interno di un file markdown dovrai scrivere:
+
+```markdown
+
+::: myapp.test.utils.sum_numbers
+
+```
+
+In automatico mkdocstring visualizzerà all'interno del sito il tuo esempio.
+
+Ovviamente consigliamo sempre di provare a modificare i file markdown e di controllare sempre il risultato, potete sempre fare in modo di aggiungere altri commenti o abbellimenti in markdown normalmente.

docs/learning/mkdocs_tutorial/extensions.en.md

@@ -0,0 +1,19 @@
+---
+title: Extensions
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+In this section, you can find MkDocs extensions that we consider most useful for creating a truly comprehensive documentation site.
+
+| Extension      | Description                          | Link                                              |
+| -------------- | ------------------------------------ | -------------------------------------------------- |
+| mkdocs-material | Feature-rich template compared to the basic mkdocs template | [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) |
+| mkdocs-git-revision-date-localized-plugin | Inserts the last modification date at the bottom of the page based on the latest commit | [mkdocs-git-revision-date-localized-plugin](https://pypi.org/project/mkdocs-git-revision-date-localized-plugin/) |
+| mkdocs-jupyter | Renders a Jupyter notebook within a page, including any charts | [mkdocs-jupyter](https://github.com/danielfrg/mkdocs-jupyter) |
+| mkdocs-static-i18n | Supports your site in multiple languages | [mkdocs-static-i18n](https://github.com/ultrabug/mkdocs-static-i18n) |
+| mkdocs-autorefs | Allows linking to another page on the site without knowing the full path | [mkdocs-autorefs](https://pypi.org/project/mkdocs-autorefs/) |
+| neoteroi-mkdocs | Allows inserting graphical elements such as cards, timelines, and Gantt charts | [neoteroi-mkdocs](https://github.com/Neoteroi/mkdocs-plugins) |
+| mkdocs-timetoread-plugin | it allows you to add an indicative reading time for a page, ideal for those who want to create a website with articles or blog posts. | https://pypi.org/project/mkdocs-timetoread-plugin/ |

docs/learning/mkdocs_tutorial/extensions.md

@@ -0,0 +1,19 @@
+---
+title: Estensioni
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+In questa sezione potete trovare le estensioni di mkdocs che sono secondo noi più utili per poter creare un sito documentale davvero completo.
+
+| Estensione      | Descrizione                          | Link|
+| ----------- | ------------------------------------ |-----------------|
+| mkdocs-material| template ricchissimo di funzionalità rispetto a mkdocs base| https://squidfunk.github.io/mkdocs-material/ |
+| mkdocs-git-revision-date-localized-plugin | permette di inserire a fondo pagina la data relativa all'ultima modifica sulla base dell'ultima commit effettuata| https://pypi.org/project/mkdocs-git-revision-date-localized-plugin/ |
+| mkdocs-jupyter    | permette di renderizzare uno jupyter notebook all'interno di una pagina compresi eventuali grafici | https://github.com/danielfrg/mkdocs-jupyter |
+| mkdocs-static-i18n    | consente di supportare il tuo sito in diverse lingue | https://github.com/ultrabug/mkdocs-static-i18n |
+|mkdocs-autorefs| permette di puntare ad un'altra pagina del sito senza conoscere il path completo | https://pypi.org/project/mkdocs-autorefs/ |
+| neoteroi-mkdocs   | permette di inserire elementi grafici come cards, timelines e diagrammi di gantt| https://github.com/Neoteroi/mkdocs-plugins |
+| mkdocs-timetoread-plugin | permette di aggiungere un tempo di lettura indicativo per una pagina, ideale per chi vuole fare un sito con articoli o blog post | https://pypi.org/project/mkdocs-timetoread-plugin/ |