Merge pull request #13 from PythonBiellaGroup/develop

add sphix vs mkdocs and secret management

Author: airaghidavide

docs/learning/mkdocs_tutorial/github_pages.md

@@ -31,3 +31,33 @@ Ecco alcune caratteristiche:
     !!! note "tip"
 
         Bisogna quindi impostare questa opzione in **Settings > Pages > Build and deployment > Source = Github Actions**
+
+## Gestione dei secrets
+
+Spesso capita che all'interno dei nostri progetti dobbiamo utilizzare dei valori che non devono essere mostrati in chiaro perchè riservati.
+
+In mkdocs é possibile inserire delle variabili di ambiente all'interno di mkdocs.yml e poi passare il vero valore dinamicamente per esempio tramite la pipeline di cicd.
+
+Un esempio é l'estensione per google analytics fornita da mkdocs material:
+
+``` { .yaml .copy }
+analytics:
+    provider: google
+    property: !ENV GOOGLE_ANALYTICS_KEY
+```
+
+In questo caso abbiamo passato il valore **GOOGLE_ANALYTICS_KEY** tramite la github actions che si occupa del deploy del sito.
+Come fare?
+
+1. Nella vostra repo andate nella sezione **Settings** e poi in **Secrets and variables**
+2. Nella sezione actions selezionate **New repository secret** e aggiungete il vostro secret
+3. All' interno dello yaml di configurazione della github actions richiamate il valore del secret in questo modo:
+
+``` { .yaml .copy }
+- name: Build mkdocs website inside docker
+  shell: bash
+  run: make docs_build
+  env:
+    GOOGLE_ANALYTICS_KEY: $<double curly brackets> secrets.GOOGLE_ANALYTICS_KEY <double curly brackets>
+
+```

docs/learning/mkdocs_tutorial/mkdocs_vs_sphinx.md

@@ -0,0 +1,25 @@
+---
+title: MkDocs vs Sphinx
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+    - sphinx
+---
+
+Nel panorama delle librerie per generare documentazione automatica e siti statici non possiamo non citare [Sphinx](https://sphinx-rtd-theme.readthedocs.io/en/stable/) che forse ha rappresentato lo standard python fino a qualche anno fa.
+
+Potete trovare già un riferimento a **sphinx** e alle sue caratteristiche all'interno di questo [articolo](../../learning/document_code/index.md)
+
+In questa sezione confrontiamo invece in maniera schematica quali sono le caratteristiche di sphinx e mkdocs in modo da poter evidenziare i punti di forza di entrambi.
+
+|                  | MkDocs                                     | Sphinx                                                                |
+| --------------- | ------------------------------------------ | --------------------------------------------------------------------- |
+| `Formati supportati`   | **Markdown**                               | **rST** ma con l'estensione myst-parser supporta il markdown        |
+| `Startup`       | Facile con il comando `poetry run mkdocs .` | Semplice con il comando `sphinx-quickstart`                          |
+| `Configurazione`| Utilizza un file yaml **mkdocs.yml**        | Utilizza un file python **conf.py**                                   |
+| `Layout`        | Elegante ed accattivante, risulta anche ben navigabile | Risulta un po' retro. Iconico il tema Read the Docs       |
+| `Build`         | Fornisce un server locale per provare interamente il sito. Comodo il comando `poetry run mkdocs serve` | Genera la build del sito ma é l'utente che lo deve poi provare nel suo browser. Questa operazione viene fatta con `make html` |
+| `Estensioni`    | Sono tantissime ma non tutte vengono mantenute | Sono presenti molte estensioni ma la community é meno attiva rispetto a mkdocs |
+| `Personalizzazione` | Possibilità infinite grazie all'integrazione dei css e ai temi disponibili | Decisamente meno personalizzabile                                |
+| `Integrazione con terze parti` | Integrazione con Confluence con questa [estensione](https://github.com/pawelsikora/mkdocs-with-confluence) | Integrazione con Confluence con questa [estensione](https://sphinxcontrib-confluencebuilder.readthedocs.io/en/stable/) |

mkdocs.yml

@@ -217,6 +217,7 @@ nav:
                       - learning/mkdocs_tutorial/deploy.md
                       - Github pages: learning/mkdocs_tutorial/github_pages.md
                 - Estensioni: learning/mkdocs_tutorial/extensions.md
+                - MkDocs vs Sphinx: learning/mkdocs_tutorial/mkdocs_vs_sphinx.md
           - Pre-commit: learning/pre-commit/index.md
           - Struttura di progetto:
                 - learning/project_structure/index.md