From a95cbc90c6a05317182d9ea4061888bf1e166473 Mon Sep 17 00:00:00 2001
From: Juliette Engelaere-Lefebvre
 <juliette.engelaere@developpement-durable.gouv.fr>
Date: Mon, 21 Nov 2022 11:20:23 +0100
Subject: [PATCH] =?UTF-8?q?am=C3=A9lioration=20doc=20configuration=20.Renv?=
 =?UTF-8?q?iron?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .gitignore                |   1 +
 DESCRIPTION               |   4 ++
 NEWS.md                   |   7 +--
 README.Rmd                |  17 +++++-
 README.md                 |  46 ++++++++++------
 dev_history.R             |   1 +
 vignettes/.gitignore      |   2 +
 vignettes/tuto_config.Rmd | 109 ++++++++++++++++++++++++++++++++++++++
 8 files changed, 166 insertions(+), 21 deletions(-)
 create mode 100644 vignettes/.gitignore
 create mode 100644 vignettes/tuto_config.Rmd

diff --git a/.gitignore b/.gitignore
index 2933612..342ba65 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,3 +5,4 @@
 .DS_Store
 docs
 debug*
+inst/doc
diff --git a/DESCRIPTION b/DESCRIPTION
index a89ab33..fc4750b 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -39,3 +39,7 @@ LazyData: true
 Roxygen: list(markdown = TRUE)
 URL: https://dreal-datalab.gitlab.io/datalibaba/index.html, https://gitlab.com/dreal-datalab/datalibaba
 RoxygenNote: 7.1.2
+Suggests: 
+    knitr,
+    rmarkdown
+VignetteBuilder: knitr
diff --git a/NEWS.md b/NEWS.md
index c01b4a0..4640dd7 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,17 +1,18 @@
 # datalibaba 0.0.0.9003
 - Correction d'un bug dans `poster_data()`, la fonction plantait si les modalités d'un facteur contenaient des caractères spéciaux.
+- Amélioration de la documentation sur la configuration du .Renviron.
 
 # datalibaba 0.0.0.9002
-- Correction d'un bug dans la fonction `importer_data()` : nommage du champ geo tel qu'il avait été chargé
+- Correction d'un bug dans la fonction `importer_data()` : nommage du champ géo tel qu'il avait été chargé
 
 # datalibaba 0.0.0.9001
 - Correction d'un bug dans la fonction `poster_data()` : paramétrage des contraintes géo selon le nom de la colonne géo. (auparavant utilisation de 'geometry' pour toutes les tables, ce qui provoquait des plantages).  
-- Ajout de message pour le post de dataset geo afin d'identifier quelle étape est en cours.
+- Ajout de message pour le post de dataset géo afin d'identifier quelle étape est en cours.
 
 # datalibaba 0.0.0.9000
 
 - ajout de la fonction `check_server_renviron()` qui vérifie si les variables système sont bien activées via .Renviron. 
-- ajout de la fonction `connect_to_db()` : Connection au serveur de base de donnees. 
+- ajout de la fonction `connect_to_db()` : Connexion au serveur de base de données. 
 - ajout de la fonction `list_schemas()` : Lister les schémas sur un connecteur. 
 - ajout de la fonction `list_tables()` : Lister les tables sur un schéma d'un connecteur. 
 - ajout de la fonction `standard_var_pg()` pour normaliser le nom des champs en vue de leur versement sur le SGBD
diff --git a/README.Rmd b/README.Rmd
index 2bbe2bd..d8cba4f 100644
--- a/README.Rmd
+++ b/README.Rmd
@@ -38,15 +38,28 @@ library(datalibaba)
 
 ### Vérifier la configuration de son poste
 
-La fonction permet de s'assurer que les variables systèmes sont bien activées.
+La fonction `check_server_renviron()` permet de s'assurer que les variables systèmes sont bien activées.
 
 ```{r, eval=FALSE}
 check_server_renviron()
 ```
 
+Elle doivent être de la forme :
+```
+server=adresse_ip
+user_does=identifiant
+pwd_does=lemotdepassesansquote
+port=lenumerodeport 
+
+```
+Le suffixe `does` du nom d'utilisateur et du mot de passe peut être remplacé par n'importe quel suffixe permettant d'identifier le rôle de connexion ou autre, par exemple, `user_dreal` et `pwd_dreal`. 
+Mais en l'état des développements actuels, la fonction `check_server_enriron()` ne les reconnaîtra pas comme valides alors qu'ils le sont.
+
+Un pas à pas complet est présenté sur la vignette 'Configurer son poste pour utiliser {datalibaba}'(`vignette("tuto_config")`).
+
 ### Se connecter
 
-con sera utilisé ensuite sur l'ensemble des autres fonctions pour dialoguer avec le serveur de base de données.
+`con` sera utilisée ensuite sur l'ensemble des autres fonctions pour dialoguer avec le serveur de base de données.
 
 ```{r, eval=FALSE}
 con <- connect_to_db(db = "datamart", user = "does")
diff --git a/README.md b/README.md
index ff13aeb..05fc3de 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,9 @@
+
 <!-- README.md is generated from README.Rmd. Please edit that file -->
 
 # datalibaba <img src='man/figures/logo.png' align="right" height="139" />
 
 <!-- badges: start -->
-
 <!-- badges: end -->
 
 {datalibaba} est un ensemble de fonctions visant à faciliter
@@ -17,8 +17,6 @@ Loire. Site web de présentation du package :
 remotes::install_gitlab('dreal-pdl/csd/datalibaba', host = "gitlab-forge.din.developpement-durable.gouv.fr")
 ```
 
-
-
 ## Example
 
 ``` r
@@ -27,16 +25,32 @@ library(datalibaba)
 
 ### Vérifier la configuration de son poste
 
-La fonction permet de s’assurer que les variables systèmes sont bien
-activées.
+La fonction `check_server_renviron()` permet de s’assurer que les
+variables systèmes sont bien activées.
 
 ``` r
 check_server_renviron()
 ```
 
+Elle doivent être de la forme :
+
+    server=adresse_ip
+    user_does=identifiant
+    pwd_does=lemotdepassesansquote
+    port=lenumerodeport 
+
+Le suffixe `does` du nom d’utilisateur et du mot de passe peut être
+remplacé par n’importe quel suffixe permettant d’identifier le rôle de
+connexion ou autre, par exemple, `user_dreal` et `pwd_dreal`. Mais en
+l’état des développements actuels, la fonction `check_server_enriron()`
+ne les reconnaîtra pas comme valides alors qu’ils le sont.
+
+Un pas à pas complet est présenté sur la vignette ‘Configurer son poste
+pour utiliser {datalibaba}’(`vignette("tuto_config")`).
+
 ### Se connecter
 
-con sera utilisé ensuite sur l’ensemble des autres fonctions pour
+`con` sera utilisée ensuite sur l’ensemble des autres fonctions pour
 dialoguer avec le serveur de base de données.
 
 ``` r
@@ -68,17 +82,17 @@ post_data(con, data = head(iris), schema = "public", table = "iris").
 
 La fonction `poster_data()` se veut plus complète :
 
-  - elle ouvre et ferme la connexion au SGBD,  
-  - elle gère les dataframes spatiaux, les variables temporelles et les
+-   elle ouvre et ferme la connexion au SGBD,  
+-   elle gère les dataframes spatiaux, les variables temporelles et les
     facteurs,  
-  - elle adapte le dataset posté pour respecter quelques contraintes
-    d’administration du SGBD (normalisation du nom des variables,
-    ajout de clé primaire, et pour les tables spatiales : ajout d’index
+-   elle adapte le dataset posté pour respecter quelques contraintes
+    d’administration du SGBD (normalisation du nom des variables, ajout
+    de clé primaire, et pour les tables spatiales : ajout d’index
     spatial, déclaration du CRS et du nb de dimensions de la
     géométrie)  
-  - poste quelques métadonnées en commentaire de la table (auteur du
+-   poste quelques métadonnées en commentaire de la table (auteur du
     chargement et sa date)  
-  - ajoute les droits de lecture/écriture du schéma à la table postée.
+-   ajoute les droits de lecture/écriture du schéma à la table postée.
 
 Le schéma spécifié en argument est créé s’il n’existe pas.
 
@@ -97,10 +111,10 @@ db_iris <- get_data(con, schema = "public", table = "iris")
 
 La fonction `importer_data()` se veut plus complète :
 
-  - elle ouvre et ferme la connexion au SGBD,
-  - elle gère les dataframes spatiaux, les variables temporelles et les
+-   elle ouvre et ferme la connexion au SGBD,
+-   elle gère les dataframes spatiaux, les variables temporelles et les
     facteurs,
-  - et ‘déstandardise’ les noms de champs si le dataset a été posté avec
+-   et ‘déstandardise’ les noms de champs si le dataset a été posté avec
     `poster_data()`,
 
 de manière à retrouver le dataframe dans l’état précis où il était avant
diff --git a/dev_history.R b/dev_history.R
index 214801c..2353b4b 100644
--- a/dev_history.R
+++ b/dev_history.R
@@ -26,6 +26,7 @@ usethis::use_package("units")
 usethis::use_package("tibble")
 usethis::use_package("tidyr")
 usethis::use_package("gtools")
+usethis::use_vignette("tuto_config")
 attachment::att_amend_desc()
 devtools::document()
 pkgdown::build_site()
diff --git a/vignettes/.gitignore b/vignettes/.gitignore
new file mode 100644
index 0000000..097b241
--- /dev/null
+++ b/vignettes/.gitignore
@@ -0,0 +1,2 @@
+*.html
+*.R
diff --git a/vignettes/tuto_config.Rmd b/vignettes/tuto_config.Rmd
new file mode 100644
index 0000000..f595d44
--- /dev/null
+++ b/vignettes/tuto_config.Rmd
@@ -0,0 +1,109 @@
+---
+title: "Configurer son poste pour utiliser `{datalibaba}`"
+output: rmarkdown::html_vignette
+vignette: >
+  %\VignetteIndexEntry{tuto_config}
+  %\VignetteEngine{knitr::rmarkdown}
+  %\VignetteEncoding{UTF-8}
+---
+
+```{r, include = FALSE}
+knitr::opts_chunk$set(
+  collapse = TRUE,
+  comment = "#>"
+)
+```
+
+
+```{r setup}
+library(datalibaba)
+```
+
+## Principes 
+
+Afin de renseigner ses identifiants de connexion une fois pour toute (sur un poste de travail) et de ne pas les faire apparaître en clair dans les scripts de préparation de données, le package `{datalibaba}` vous propose de saisir ces informations dans votre fichier de variables d'environnement R, intitulé .Renviron.
+
+
+Les variables d'environnement utilisées par `{datalibaba}` doivent être de la forme :
+```
+server=adresse_ip
+user_does=identifiant
+pwd_does=lemotdepassesansquote
+port=lenumerodeport 
+
+```
+Il ne faut pas mettre entre '' ou "" la valeur de ces variables.
+
+Le suffixe `does` du nom d'utilisateur et du mot de passe peut être remplacé par n'importe quel suffixe permettant d'identifier le rôle de connexion ou autre, par exemple, `user_dreal` et `pwd_dreal`. 
+Mais en l'état des développements actuels, la fonction `check_server_enriron()`, qui vérifie la configuration de votre poste ne les reconnaîtra pas comme valides alors qu'ils le sont.
+
+## Procédure pas à pas
+
+#### 1ère étape
+
+Ouvrir le fichier de variables d'environnement R (.Renviron) avec  :
+```{r, eval = FALSE}
+# install.packages("usethis")
+usethis::edit_r_environ()
+```
+Dans Rstudio, ce fichier s'ouvre dans le cadran dévolu à l'édition des scripts.
+
+#### 2e étape  
+Saisir les 4 variables d'environnement nécessaires à la connexion sur ce fichier texte. 
+Cette saisie doit prendre la forme :   
+```
+ server=11.22.333.444  
+ user_does=utilisateur  
+ pwd_does=lemotdepassesansquote  
+ port=5432  
+```
+
+#### 3e étape
+Enregistrer le fichier .Renviron, le fermer, redémarrer la session R pour que ces nouvelles variables soit lues. 
+La configuration est terminée. 
+`{datalibaba}` peut maintenant être utilisé.
+
+## Usage 
+
+#### Utilisateur suffixé "_does"
+
+Dans le cas d'identifiants de connexion déclarés avec le suffixe '_does', il n'est plus nécessaire de préciser ensuite quels identifiants de connexion il faut utiliser. 
+Par défaut les fonctions de connexion, de lecture ou d'écriture de données vont silencieusement utiliser `user_does` et `pwd_does`.
+
+#### Autres utilisateurs
+Dans les autres cas, il faudra préciser les identifiants de connexion à utiliser avec le paramètre `user`, par exemple, les fonctions : 
+```{r, eval = FALSE}
+poster_data(data = iris, table = "test_iris", schema = "public", db = "public", pk = NULL, 
+            post_row_name = FALSE, overwrite = TRUE, user = "dema")
+
+importer_data(table = "test_iris", schema = "public", db = "public", user = "dema")
+```
+
+vont aller chercher les identifiants / mot de passe dans le .Renviron déclarés au niveau des variables d'environnement `user_dema` et `pwd_dema`.
+
+#### Plusieurs serveurs ou port de base de données
+Les fonctions de {datalibaba} utilisent par défaut, et silencieusement, les variables d'environnement `server`, `user_does`, `pwd_does`, `port`. 
+
+Si l'utilisateur souhaite recourir à un serveur autre que celui renseigné au niveau de la variable d'environnement `serveur` ou utiliser un autre port que celui par défaut, il peut créer de nouvelles variables d'environnement dans le .Renviron avec la procédure détaillée ci dessus et les appeler grâce à la fonction `Sys.getenv("server_local")`.
+
+Voici un exemple de configuration secondaire : 
+
+Ajouts au fichier .Renviron :    
+```
+server_local=127.0.0.1 
+user_local=admin  
+pwd_local=lemotdepassesansquote  
+```  
+
+Utilisation dans un scripts de datapréparation
+
+```{r, eval = FALSE}
+poster_data(data = iris, table = "test_iris", schema = "public", db = "public", pk = NULL, overwrite = TRUE, 
+            post_row_name = FALSE, user = "local", server = Sys.getenv("server_local"))
+
+importer_data(table = "test_iris", schema = "public", db = "public", 
+              user = "local", server = Sys.getenv("server_local"))
+```
+
+
+
-- 
GitLab