add mkdocs tutorial

airaghidavide · airaghidavide · commit 2547dd014e16 · 2024-01-30T22:36:47.000+01:00
diff --git a/docs/learning/mkdocs_tutorial/deploy.en.md b/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.
diff --git a/docs/learning/mkdocs_tutorial/deploy.md b/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.
diff --git a/docs/learning/mkdocs_tutorial/extensions.en.md b/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/ |
diff --git a/docs/learning/mkdocs_tutorial/extensions.md b/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/ |
diff --git a/docs/learning/mkdocs_tutorial/github_pages.en.md b/docs/learning/mkdocs_tutorial/github_pages.en.md
@@ -0,0 +1,33 @@
+---
+title: GitHub Pages
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+There are various hosting services to consider when hosting a website. In this tutorial, we will show you how to publish and host a site on **GitHub Pages**.
+
+## What is GitHub Pages
+
+GitHub Pages is a free web hosting service provided by GitHub. It allows users to publish static websites directly from a GitHub repository.
+Here are some features:
+
+- Only static websites can be hosted.
+- The hosting service is free.
+- By default, a domain like https://username.github.io/my-project is set up, but you can configure a domain from another provider.
+
+## Getting Started
+
+1. Create your repository on GitHub.
+2. After creating your repository, ensure that the repository is public to use GitHub Pages. For those with a GitHub Enterprise subscription, it's possible to keep the repository private.
+
+    !!! note "tip"
+    
+        To check if the repository is public, go to **Settings > Danger Zone > Change repository visibility.**
+
+3. To publish on GitHub Pages, we use GitHub Actions, which allows building CI/CD pipelines from a YAML configuration file. 
+    
+    !!! note "tip"
+    
+        Set this option in **Settings > Pages > Build and deployment > Source = GitHub Actions.**
diff --git a/docs/learning/mkdocs_tutorial/github_pages.md b/docs/learning/mkdocs_tutorial/github_pages.md
@@ -0,0 +1,33 @@
+---
+title: Github Pages
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+Ci sono vari servizi di hosting che si possono valutare per ospitare un sito. In questo tutorial vi mostreremo come poter pubblicare e ospitare un sito su **Github Pages**.
+
+## Cos'é Github Pages
+
+GitHub Pages è un servizio di hosting web gratuito offerto da GitHub. Consente agli utenti di pubblicare siti web statici direttamente da una repository github.
+Ecco alcune caratteristiche:
+
+- Possono essere hostati solo siti web statici.
+- Il servizio di hosting é gratuito
+- Di default viene impostato un dominio del tipo https://username.github.io/my-project ma é possibile impostare un dominio di un altro provider.
+
+## Primi passi
+
+1. Creare la propria repository su Github
+2. Dopo aver creato la propria repository é necessario assicurarsi che la repository sia pubblica per poter usufruire di Github Pages. Per chi possiede una sottoscrizione a github enterprise é possibile mantenere la repository privata.
+
+    !!! note "tip"
+    
+        Per verificare che la repository sia pubblica andare su **Settings > Danger Zone > Change repository visibility.**
+
+3. Per poter pubblicare su github Pages noi utilizziamo le github actions che permettono di costruire delle pipeline di CI/CD a partire da un file di configurazione YAML.
+
+    !!! note "tip"
+    
+        Bisogna quindi impostare questa opzione in **Settings > Pages > Build and deployment > Source = Github Actions**
diff --git a/docs/learning/mkdocs_tutorial/index.en.md b/docs/learning/mkdocs_tutorial/index.en.md
@@ -0,0 +1,36 @@
+---
+title: Intro
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+## What is MkDocs?
+
+MkDocs is a documentation generation tool designed to simplify the process of creating documents for software projects, personal web pages, and more. With MkDocs, you can write documentation using the Markdown markup language, making the process of creating and maintaining documentation accessible even to those who are not familiar with more complex markup languages like HTML.
+
+## Why Use MkDocs?
+
+There are several reasons to choose MkDocs as a tool for documentation creation. Here are some of the main motivations:
+
+1. **Ease of use**: MkDocs is based on the Markdown markup language, known for its simplicity and clarity. This makes the creation and maintenance of documentation accessible even to those who are not familiar with more complex markup languages like HTML.
+
+2. **Speed in creation**: MkDocs simplifies the documentation creation process. With just a few commands, you can initialize a project, add new pages, and generate a complete documentation site. This allows you to focus more on content, reducing the time required for documentation creation.
+
+3. **Professional and elegant appearance**: MkDocs generates documentation websites with a modern and elegant design. The clean appearance and intuitive navigation enhance the user experience, making the documentation more enjoyable to read and consult.
+
+4. **Flexible configuration**: MkDocs offers many configuration options that allow you to customize the appearance and behavior of the documentation site. You can customize the theme, add navigation elements, and embed code snippets to tailor the documentation to the needs of your project.
+
+5. **Large support community**: MkDocs has an active community and a plugin ecosystem that provides additional functionality. You can find support online, tutorials, and additional resources thanks to the community that continually contributes to the improvement of the MkDocs ecosystem.
+
+## What Will We Cover?
+
+In this tutorial, we will explore step by step how to use MkDocs to create clean and easily navigable documentation for your project. You can also use MkDocs to build a site for a community (as we did 😉).
+
+* Introduction to MkDocs
+* Initializing the project
+* Creating documentation pages using Markdown.
+* Customizing the appearance of your documentation site.
+* Developing your site locally
+* Deploying your site
diff --git a/docs/learning/mkdocs_tutorial/index.md b/docs/learning/mkdocs_tutorial/index.md
@@ -0,0 +1,36 @@
+---
+title: Intro
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+## Cos'é MkDocs?
+
+MkDocs è uno strumento di generazione di documentazione progettato per semplificare il processo di creazione di documenti per progetti software, pagine web personali e altro ancora. Con MkDocs, è possibile scrivere la documentazione utilizzando il linguaggio di markup Markdown, rendendo il processo di creazione e manutenzione della documentazione accessibile anche a chi non è esperto di HTML o altri linguaggi di markup più complessi.
+
+##  Perchè utilizzare MkDocs?
+
+Ci sono diverse ragioni per scegliere MkDocs come strumento per la creazione della documentazione. Ecco qualche esempio:
+
+1. **Semplicità d'uso**: MkDocs si basa sul linguaggio di markup Markdown, che è noto per la sua semplicità e chiarezza. Questo rende la creazione e la manutenzione della documentazione accessibile anche a coloro che non hanno familiarità con linguaggi di markup più complessi come HTML.
+
+2. **Rapidità nella creazione**: MkDocs semplifica il processo di creazione della documentazione. Con pochi comandi, è possibile inizializzare un progetto, aggiungere nuove pagine e generare un sito di documentazione completo. Ciò consente di concentrarsi maggiormente sul contenuto, riducendo il tempo necessario per la creazione della documentazione.
+
+3. **Aspetto professionale ed elegante**: MkDocs genera siti web di documentazione con un design moderno ed elegante. L'aspetto pulito e la navigazione intuitiva migliorano l'esperienza dell'utente, rendendo la documentazione più piacevole da leggere e consultare.
+
+4. **Configurazione flessibile**: MkDocs offre molte opzioni di configurazione che consentono di personalizzare l'aspetto e il comportamento del sito di documentazione. Puoi personalizzare il tema, aggiungere elementi di navigazione e incorporare snippet di codice per adattare la documentazione alle esigenze del tuo progetto.
+
+5. **Ampia community**: MkDocs gode di una comunità attiva e di un ecosistema di plugin che offre ulteriori funzionalità. Puoi trovare supporto online, tutorial, e risorse aggiuntive grazie alla comunità che contribuisce continuamente al miglioramento dell'ecosistema MkDocs.
+
+## Cosa vedremo?
+
+In questo tutorial, esploreremo passo dopo passo come utilizzare MkDocs per creare una documentazione pulita e facilmente navigabile per il tuo progetto. Puoi usare Mkdocs anche per poter realizzare un sito per una community (come abbiamo fatto noi 😉)
+
+* Introduzione a MkDocs
+* Inizializzare il progetto 
+* Creare pagine di documentazione utilizzando il Markdown.
+* Personalizzare l'aspetto del tuo sito di documentazione.
+* Sviluppare il tuo sito in locale
+* Deployare il tuo sito
diff --git a/docs/learning/mkdocs_tutorial/setup.en.md b/docs/learning/mkdocs_tutorial/setup.en.md
@@ -0,0 +1,62 @@
+---
+title: Setup
+disquis: PythonBiellaGroup
+timetoread: true
+tags:
+    - mdkocs
+---
+
+## Installation
+
+You can install MkDocs like any other Python library, but it is advisable to use a dependency manager such as PDM or Poetry.
+
+```shell
+poetry add mkdocs
+```
+In addition to the basic installation of MkDocs, you can use various templates that enhance the configuration and initial layout of MkDocs. The library we prefer and recommend is MkDocs Material, which is among the most widely used and appreciated. We will explore some of the features it provides in this tutorial.
+
+```shell
+poetry add mkdocs-material
+```
+
+With MkDocs, you have the option to enhance functionality with numerous interesting and highly useful extensions, providing a better user experience.
+
+## Initialization
+
+Once you have finished developing your code, you can run this command:
+
+```shell
+poetry mkdocs new .
+```
+
+The result of this instruction is the creation of:
+
+- **docs folder**: In this folder, you can place all the Markdown files that will constitute the documentation.
+- **mkdocs.yml**: It is the main configuration file of MkDocs where you set all the properties of the documentation site.
+
+## mkdocs.yml
+
+This file is the most important in MkDocs and provides all the information needed to create and customize the final site.
+
+Here are some of the main sections:
+
+| Section               | Attributes                                               | Description                                   | 
+|-----------------------|----------------------------------------------------------|-----------------------------------------------|
+| project information    | site_name, site_url, author, site_description             | Basic information for the site                |
+| repo information       | repo_name, repo_url                                      | It is possible to link the repository to the site, allowing visitors to view the source code |
+| nav                   | --                                                       | Defines the site's tree structure; it can be built on multiple levels |
+| extra css              | extra_css                                                | It is possible to extend certain aspects of the site with custom CSS |
+| theme                 | --                                                       | Properties of the chosen theme; in our case, mkdocs-material |
+| markdown_extensions    | --                                                       | Here we can specify the properties of our Markdown that will determine the layout of individual pages within the site |
+| plugins               | --                                                       | In this section, we specify all the plugins we have installed with the options required for each |
+| extra                 | analytics, social, consent, alternate                    | In this section, we can specify additional functionalities for our site, including: linking to Google Analytics, social links in the footer of the site, consent to use cookies, and a switcher for multilingual sites |
+
+## Run locally
+After compiling the mkdocs.yml file and creating the Markdown files inside the docs folder, you can check the final result locally by running:
+
+```shell
+poetry run mkdocs serve
+```
+
+MkDocs will generate all artifacts in the **site** folder and make the site available at **http://127.0.0.1:8000/**.
+
diff --git a/docs/learning/mkdocs_tutorial/setup.md b/docs/learning/mkdocs_tutorial/setup.md
diff --git a/mkdocs.yml b/mkdocs.yml
diff --git a/poetry.lock b/poetry.lock
