amélioration doc configuration .Renviron

.gitignore

@@ -5,3 +5,4 @@
 .DS_Store
 docs
 debug*
+inst/doc

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

NEWS.md

 # 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

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")

README.md

+
 <!-- 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

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()

vignettes/.gitignore

+*.html
+*.R

vignettes/tuto_config.Rmd

+---
+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"))
+```
+
+
+