FabNum/Code
4
0
Fork 0
Code Issues 2 Pull Requests Actions Packages Projects 1 Releases Wiki Activity

Amélioration de la documentation

Browse Source
This commit is contained in:
Stéphan Peccini 2025-05-15 17:49:52 +02:00
parent 4ae0fbfdb3
commit cf604957e3
4 changed files with 75 additions and 46 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

106
README.md
View File

@ -14,7 +14,7 @@ Le code proposé répond à la partie outillage, avec une architecture modulaire
Le projet est bâti sur un backeng Gitea pour la gestion des fiches et des tickets d'évolution. (Accéder au backend)[https://fabnum-git.peccini.fr/FabNum/Fiches] Le projet est bâti sur un backeng Gitea pour la gestion des fiches et des tickets d'évolution. (Accéder au backend)[https://fabnum-git.peccini.fr/FabNum/Fiches]
Le serveur qui héberge l'application héberge aussi le service Gitea, ce qui permet d'éliminer les temps de latence dus au réseau. Le serveur qui héberge l'application héberge aussi le service Gitea, ce qui permet d'éliminer les temps de latence dus au réseau. Les fiches sont toutefois mise en cache localement en générant les fichiers markdown (référence), html (affichage) et pdf (download).
L'application est écrite en python et utilise majoritairement streamlit. L'application est écrite en python et utilise majoritairement streamlit.
@ -26,11 +26,14 @@ Le fichier **requirements.txt** permet d'installer tout ce qui est nécessaire p
python -m venv venv python -m venv venv
source venv/bin/activate source venv/bin/activate
# Installation depuis le fichier
pip install -r requirements.txt pip install -r requirements.txt
# Génération du fichier
pipreqs requirements.txt
### Environnement ### Environnement
Le fichier **.env.local** qui contient GITEA_TOKEN n'est pas dans le dépôt car il contient la clé pour accéder au backend. Le fichier **.env.local** qui contient GITEA_TOKEN n'est pas dans le dépôt car il contient la clé pour accéder au backend. Il doit donc être créé ainsi que le Token. Le TOken doit permetre l'accès en lecture au dépôt et en lecture/écriture au gestionnaire des tickets.
Pour l'environnement de pré-production, (https://fabnum-dev.peccini.fr)[https://fabnum-dev.peccini.fr] : Pour l'environnement de pré-production, (https://fabnum-dev.peccini.fr)[https://fabnum-dev.peccini.fr] :
@ -52,7 +55,7 @@ Pour l'environnement de production, (https://fabnum.peccini.fr)[https://fabnum.p
PORT=8501 PORT=8501
La différence entre les deux environnements se fait au travers de la configuration du proxy Nginx (ici celle de dev ; il suffit de changer dev en public pour l'environnement de production) : La différence entre les deux environnements se fait au travers de la configuration du proxy Nginx (ci-après celle de dev ; il suffit de changer dev en public pour l'environnement de production) :
# Ajout d'un en-tête personnalisé pour indiquer l'environnement # Ajout d'un en-tête personnalisé pour indiquer l'environnement
add_header X-Environment "dev" always; add_header X-Environment "dev" always;
@ -106,11 +109,19 @@ Le cœur de l'application. Ce script sert de point d'entrée et d'orchestrateur
Ce fichier est conçu de manière modulaire, déléguant les fonctionnalités spécifiques aux modules spécialisés, ce qui facilite la maintenance et les évolutions futures. Ce fichier est conçu de manière modulaire, déléguant les fonctionnalités spécifiques aux modules spécialisés, ce qui facilite la maintenance et les évolutions futures.
Dans la sidebar, l'application indique une estimation des émissions de gaz à effet de serre. Pour cela, un mécanisme est mis en place dans la configuration Nginx pour enregistrer dans le fichier :
/var/log/nginx/fabnum-dev.access.log
les informations d'octets transférés.
Ce système est basé sur la création d'un cookie de session, utilisé ensuite pour distinguer les utilisations.
<<<<<<<<<<<à compléter avec la configuration Nginx>>>>>>>>>>>
## Architecture et principes de conception ## Architecture et principes de conception
### Modularité et simplification ### Modularité et simplification
L'application a été restructurée selon les principes suivants : L'application a été structurée selon les principes suivants :
1. **Séparation des responsabilités** : Chaque module a une fonction bien définie 1. **Séparation des responsabilités** : Chaque module a une fonction bien définie
2. **Modularité** : Les fonctionnalités sont décomposées en composants réutilisables 2. **Modularité** : Les fonctionnalités sont décomposées en composants réutilisables
@ -149,43 +160,56 @@ L'application est organisée de façon modulaire, avec une structure simplifiée
``` ```
fabnum-dev/ fabnum-dev/
├── fabnum.py # Point d'entrée principal ├── fabnum.py # Point d'entrée principal
├── config.py # Configuration et variables d'environnement ├── config.py # Configuration et variables d'environnement
├── app/ # Modules fonctionnels principaux ├── app/ # Modules fonctionnels principaux
│ ├── analyse/ # Module d'analyse des chaînes de dépendance │ ├── analyse/ # Module d'analyse des chaînes de dépendance
│ │ ├── interface.py # Interface utilisateur pour l'analyse │ │ ├── interface.py # Interface utilisateur pour l'analyse
│ │ ├── sankey.py # Génération des diagrammes Sankey │ │ ├── sankey.py # Génération des diagrammes Sankey
│ │ └── README.md # Documentation du module │ │ └── README.md # Documentation du module
│ ├── fiches/ # Gestion et affichage des fiches │ ├── fiches/ # Gestion et affichage des fiches
│ │ ├── interface.py # Interface utilisateur pour les fiches │ │ ├── interface.py # Interface utilisateur pour les fiches
│ │ ├── generer.py # Génération des fiches │ │ ├── generer.py # Génération des fiches
│ │ ├── utils/ # Utilitaires spécifiques aux fiches │ │ ├── utils/ # Utilitaires spécifiques aux fiches
│ │ └── README.md # Documentation du module │ │ ├── utils/dynamic # Gestion de la génération et affichage des fiches par type d'opération
│ ├── personnalisation/ # Personnalisation de la chaîne │ │ ├── utils/tickets # Gestion de l'affichage et de la création des tickets
│ │ ├── interface.py # Interface principale │ │ ├── utils/fiches_utils.py # Outils de gestion et rendu des fiches
│ │ ├── ajout.py # Ajout de produits │ │ └── README.md # Documentation du module
│ │ ├── modification.py # Modification de produits │ ├── personnalisation/ # Personnalisation de la chaîne
│ │ ├── import_export.py # Import/export de configurations │ │ ├── interface.py # Interface principale
│ │ └── README.md # Documentation du module │ │ ├── ajout.py # Ajout de produits
│ └── visualisations/ # Visualisations graphiques │ │ ├── modification.py # Modification de produits
│ ├── interface.py # Interface des visualisations │ │ ├── import_export.py # Import/export de configurations
│ ├── graphes.py # Gestion des graphes à visualiser │ │ └── README.md # Documentation du module
│ └── README.md # Documentation du module │ └── visualisations/ # Visualisations graphiques
├── components/ # Composants d'interface réutilisables │ ├── interface.py # Interface des visualisations
│ ├── sidebar.py # Barre latérale de navigation │ ├── graphes.py # Gestion des graphes à visualiser
│ ├── header.py # En-tête de l'application │ └── README.md # Documentation du module
│ ├── footer.py # Pied de page ├── components/ # Composants d'interface réutilisables
│ └── README.md # Documentation des composants │ ├── sidebar.py # Barre latérale de navigation
├── utils/ # Utilitaires partagés │ ├── header.py # En-tête de l'application
│ ├── gitea.py # Connexion API Gitea │ ├── footer.py # Pied de page
│ ├── graph_utils.py # Manipulation des graphes │ ├── connexion.py # Module de connexion à partir d'un token Gitea
│ └── README.md # Documentation des utilitaires │ └── README.md # Documentation des composants
├── assets/ # Ressources statiques ├── utils/ # Utilitaires partagés
│ ├── styles/ # Feuilles de style CSS │ ├── gitea.py # Connexion API Gitea
│ └── impact_co2.js # Calcul d'impact environnemental │ ├── graph_utils.py # Manipulation des graphes
├── .env # Configuration versionnée │ ├── translations.py # Module de gestion de l'internationalisation
├── .env.local # Configuration locale (non versionnée) │ ├── visualisations.py # Manipulation des graphes de l'onglet Visualisations
└── requirements.txt # Dépendances Python │ └── README.md # Documentation des utilitaires
├── assets/ # Ressources statiques
│ ├── locales/ # Gestion de l'internationalisation
│ ├── styles/ # Feuilles de style CSS
│ ├── confir.yaml # Définition des seuils pour les indices
│ ├── fiches_labels.csv # Dictionnaire d'association entre les fiches et leurs labels (tickets)
│ ├── impact_co2.js # Calcul d'impact environnemental
│ ├── licence.md # Licence ajoutée à toutes les fiches
│ └── weakness.png # Icône de l'onglet dans le navigateur
├── .env # Configuration versionnée
├── .env.local # Configuration locale (non versionnée)
└── requirements.txt # Dépendances Python
├── .streamlit/ # Configuration streamlit côté serveur
│ └── config.toml # Fichier de configuration : important theme.base = light
``` ```
Chaque module dispose de sa propre documentation détaillée dans un fichier README.md. Chaque module dispose de sa propre documentation détaillée dans un fichier README.md.

9
assets/README.md
View File

@ -2,9 +2,12 @@
## Styles ## Styles
Le fichier **styles.css** a été construit pour agir sur le styme produit par Streamlit ou pour décorer des éléments construits par fabnum.py Le fichier **base.css** a été construit pour agir sur le style produit par Streamlit ou pour décorer des éléments construits par fabnum.py, indépendamment du thème choisi
Les deux fichiers **theme-light.css** et **theme-dark.css** contiennent les variables utilisées par base.css pour afficher les couleurs.
Il sera important de regarder s'il est possible d'interagir avec le css de Streamlit sans passer par des déclarations !important Streamlit utilise le theme par défaut du système du poste de travail de l'internaute. Afin de maîtriser complètement le thème avec base.css, il est important que la configuration côté serveur de Streamlit soit forcée au thème light dans le fichier .streamlit/config.toml :
[theme]
base = "light"
## Icone ## Icone
@ -37,4 +40,4 @@ La dernière colonne donne le label de l'item associé à la fiche.
Les labels associés aux fiches dans ce fichier doivent, bien évidemment, être **totalement égaux** aux labels de la gestion des tickets. Les labels associés aux fiches dans ce fichier doivent, bien évidemment, être **totalement égaux** aux labels de la gestion des tickets.
Ces labels avec en plus la branche permettent de faire le lien exact entre une fiche présentée dans l'application et le système de gestion des tickets. Ces labels avec en plus la branche permettent de faire le lien exact entre une fiche présentée dans l'application et le système de gestion des tickets.

5
components/README.md
View File

@ -10,11 +10,12 @@ Le module components comprend plusieurs fichiers clés :
- **header.py** : Composant d'en-tête unifié pour toutes les pages - **header.py** : Composant d'en-tête unifié pour toutes les pages
- **footer.py** : Pied de page standardisé incluant les mentions légales et informations de contact - **footer.py** : Pied de page standardisé incluant les mentions légales et informations de contact
- **fiches.py** : Composants spécifiques à l'affichage et à la manipulation des fiches - **fiches.py** : Composants spécifiques à l'affichage et à la manipulation des fiches
- **connexion.py** : Composants spécifiques à la gestion de la connexion / déconnexion sur la base d'un token Gitea
## Fonctionnalités ## Fonctionnalités
### Barre latérale (sidebar.py) ### Barre latérale (sidebar.py)
- Menu de navigation principal entre les différentes sections - Menu de navigation prin>>>>>>>>>>>>> cipal entre les différentes sections
- Options de configuration et de personnalisation - Options de configuration et de personnalisation
- Affichage des informations sur l'impact environnemental - Affichage des informations sur l'impact environnemental
- Gestion du thème (clair/sombre) - Gestion du thème (clair/sombre)
@ -45,4 +46,4 @@ afficher_menu()
afficher_pied_de_page() afficher_pied_de_page()
``` ```
Cette approche modulaire permet de maintenir une interface cohérente tout en facilitant les mises à jour de l'interface utilisateur. Cette approche modulaire permet de maintenir une interface cohérente tout en facilitant les mises à jour de l'interface utilisateur.

1
components/connexion.py
View File

@ -42,6 +42,7 @@ def connexion():
with st.form("auth_form"): with st.form("auth_form"):
# Ajout d'un champ identifiant fictif pour activer l'autocomplétion navigateur # Ajout d'un champ identifiant fictif pour activer l'autocomplétion navigateur
# et permettre de stocker le token comme un mot de passe par le navigateur # et permettre de stocker le token comme un mot de passe par le navigateur
# L'identifiant n'est donc pas utilisé par la suite ; il est caché en CSS
identifiant = st.text_input(str(_("auth.username")), value="fabnum-connexion", key="nom_utilisateur") identifiant = st.text_input(str(_("auth.username")), value="fabnum-connexion", key="nom_utilisateur")
token = st.text_input(str(_("auth.token")), type="password") token = st.text_input(str(_("auth.token")), type="password")
submitted = st.form_submit_button(str(_("auth.login"))) submitted = st.form_submit_button(str(_("auth.login")))