Mise en place d’une documentation Sphinx sur IBM i

Introduction

Introduction

Cet article à pour but de présenter la possibilité d’exploiter diverses solutions libres et gratuites très répandues dans le monde OpenSource. L’objectif est de découvrir Sphinx, un outil de génération de documentation sous forme de site web. Il est notamment utilisé pour réaliser les documentations suivantes :

  • La référence de l’OpenSource sur IBM i, IBM i OSS Docs – ici
  • La documentation de Sphinx – ici
  • Le Kernel Linux – ici
  • Le langage de programmation Python – ici
  • Le logiciel de conception 3D Blender – ici
  • Le moteur de jeu OpenSource Godot – ici

Nous allons donc voir en quelques étapes simples comment publier et maintenir votre documentation directement sur votre IBM i.

Prérequis

  • PASE (IBM Portable Application Solutions Environment for i)
  • Environnement OpenSource sur l’IBM i
  • Python sur votre IBM i (Pour rappel, les modules OpenSource comme python sont compilés et mis à disposition par IBM spécialement pour l’IBM i, il n’y a pas plus de risque à les utiliser qu’à utiliser des logiciels sous licence)

Etape 1 – Mise en place de l’environnement

Cette section est réalisée via qsh, qp2term ou ssh.

Le projet sera structuré comme suit :

/home/demosphinx sera le répertoire du projet, il contiendra les sources (doc/) et l’environnement de travail python (env/).
/www/demosphinx sera le répertoire du serveur Apache permettant de publier localement la documentation

Création des répertoires :

$ mkdir /home/demosphinx/
$ mkdir /home/demosphinx/doc
$ mkdir /home/demosphinx/env

Une fois l’arborescence créée, on installe ou met à jour Python 3.9 :

$ yum install python39

On crée ensuite un environnement virtuel pour python afin d’éviter d’être impacté par des changements de versions et pour isoler notre environnement de travail :

// Création de l'environnement virtuel Python
$ python3.9 -m venv --system-site-packages /home/demosphinx/env

// Entrer dans l'environnement virtuel
$ source /home/demosphinx/env/bin/activate

// Mise à jour du gestionnaire de paquets python (pip)
(env) $ pip install --upgrade pip
// Installation et mise à jour de Sphinx
(env) $ pip install --upgrade sphinx
// Installation du thème ReadTheDocs (Facultatif)
(env) $ pip install sphinx-rtd-theme

D’autres modules peuvent être intéressant, comme myst-parser (qui permet notamment d’utiliser du MarkDown pour rédiger sa documentation) et sphinx-jinja (qui permet l’usage de variables dans les pages). Il existe également une grande quantité de thèmes natifs présentés ici et des thèmes tiers présentés ici.

Etape 2 – Création du projet

Cette section est réalisée via qsh, qp2term ou ssh.

L’environnement en place on peut très simplement créer notre documentation.

// Entrer dans l'environnement virtuel
$ source /home/demosphinx/env/bin/activate

// Positionnement dans le répertoire du projet
$ cd /home/demosphinx/doc

// Génération du projet
$ sphinx-quickstart

On arrive ensuite sur un assistant qui va nous guider pour saisir les informations de base nécessaires à la documentation (qui seront toujours modifiables dans les sources de la documentation) : Le nom du projet, ceux des auteurs, la version, la langue de la documentation, etc… Voici un exemple :

Bienvenue dans le kit de démarrage rapide de Sphinx 7.3.7.
Veuillez saisir des valeurs pour les paramètres suivants (tapez Entrée pour accepter la valeur par défaut, lorsque celle-ci est indiquée entre crochets).

Chemin racine sélectionné : .
Vous avez deux options pour l'emplacement du répertoire de construction de la sortie de Sphinx.
Soit vous utilisez un répertoire "_build" dans le chemin racine, soit vous séparez les répertoires "source" et "build" dans le chemin racine.
> Séparer les répertoires source et de sortie (y/n) [n]: y

Le nom du projet apparaîtra à plusieurs endroits dans la documentation construite.
> Nom du projet: SphinxOnIBMi
> Nom(s) de(s) l'auteur(s): Gaia Mini Systèmes
> Version du projet []: v0

Si les documents doivent être rédigés dans une langue autre que l'anglais, vous pouvez sélectionner une langue ici grâce à son id entifiant. Sphinx utilisera ensuite cette langue pour traduire les textes que lui-même génère.

Pour une liste des identifiants supportés, voir
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Langue du projet [en]: fr

Fichier en cours de création /home/demosphinx/doc/source/conf.py.
Fichier en cours de création /home/demosphinx/doc/source/index.rst.
Fichier en cours de création /home/demosphinx/doc/Makefile.
Fichier en cours de création /home/demosphinx/doc/make.bat.

Terminé : la structure initiale a été créée.

Vous devez maintenant compléter votre fichier principal /home/demosphinx/source/index.rst et créer d'autres fichiers sources de documentation. Utilisez le Makefile pour construire la documentation comme ceci :
   make builder
où « builder » est l'un des constructeurs disponibles, tel que html, latex, ou linkcheck.

Le projet de documentation est maintenant généré !

Les différentes pages sont à ajouter dans le répertoire source/ :

  • index.rst (ou index.md si le module MarkDown est installé) – Il s’agit du point d’entrée de la documentation.
  • conf.py contient les informations de création de la documentation comme le thème, la langue, les différents format interprétés, etc…

Voici un exemple de fichier de configuration :

# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information

project = 'SphinxOnIBMi'
copyright = '2024, Gaia'
author = 'Gaia'

# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

extensions = []

templates_path = ['_templates']
exclude_patterns = []

language = 'fr'

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

html_theme = 'alabaster'
html_static_path = ['_static']

Les différents fichiers sources peuvent être édités directement sur l’IBM i via VSCode, RDi…

Etape 3 – Création de la page Apache via HTTPAdmin

Cette section est réalisée via HTTPAdmin.

Avant de générer la documentation en tant que telle, créons un petit serveur Apache basique (on pourrait tout à fait utiliser une instance nginx). Pour se faire nous allons passer par HTTPAdmin afin d’exploiter l’assistant de configuration pour créer le serveur :

L’instance Apache est maintenant créée :

Pour éviter les problèmes de CCSID, il est préférable de supprimer au préalable le fichier index.html qui sera regénéré par Sphinx.

Etape 4 – Génération de la documentation

Cette section est réalisée via qsh, qp2term ou ssh.

Revenons sur notre environnement PASE pour générer la documentation, pour cela, une simple commande suffit :

// Entrer dans l'environnement virtuel
$ source /home/demosphinx/env/bin/activate

// Génération de la documentation vers le répertoire de l'instance Apache
$ sphinx-build -b html /home/demosphinx/doc/source /www/demosphinx/htdocs -E

Sphinx v7.4.7 en cours d'exécution chargement des traductions [fr]... fait
construction en cours [mo] : cibles périmées pour les fichiers po 0
Écriture...
construction [html] : cibles périmées pour les fichiers sources 1
mise à jour de l'environnement : [nouvelle configuration] 1 ajouté(s), 0 modifié(s), 0 supprimé(s)
lecture des sources... [100%] index

Recherche des fichiers périmés... aucun résultat trouvé

Environnement de sérialisation... fait
vérification de la cohérence... fait
documents en préparation... fait
copie des ressources...
Copie des fichiers statiques... fait
copie des fichiers complémentaires... fait
copie des ressources: fait
Écriture... [100%] index

génération des index... genindex fait
Écriture des pages additionnelles... search fait
Export de l'index de recherche en French (code: fr)... fait
Export de l'inventaire des objets... fait
La compilation a réussi.

Les pages HTML sont dans /www/demosphinx/htdocs.

Voici les fichiers produits par la génération, directement dans notre instance Apache :

On voit entre autre le script Java Script, searchindex.js, un moteur de recherche intégré directement dans la documentation, l’un des gros points forts de Sphinx.

Démarrage de l’instance et résultat

On peut démarrer notre instance via HTTPAdmin :

Ou via 5250 et la commande :

STRTCPSVR SERVER(*HTTP) HTTPSVR(DEMOSPHINX)

Voici le résultat avant d’avoir rédigé la documentation :


Il ne reste plus qu’à remplir la documentation et à jouer avec les différentes possibilités de Sphinx et de ses modules.

Pour plus de détails

Documentation Sphinx :https://www.sphinx-doc.org
Documentation Build Sphinx : https://www.sphinx-doc.org/en/master/man/sphinx-build.html
Documentation ReadTheDocs :https://docs.readthedocs.io
/par
, , Trigger sur insert

Vous voulez créer un trigger qui vous indique la création d’un enregistrement dans un fichier par exemple pour superviser, dans notre exemple on enverra un email , il est conseillé de faire un fichier de paramétrage

En CLLE soit le programme Alerte_msg


             PGM        PARM(&BUFFER &BUFLEN)             
/* Paramètres */                                          
             DCL        VAR(&BUFFER) TYPE(*CHAR) LEN(200) 
             DCL        VAR(&BUFLEN) TYPE(*CHAR) LEN(4)   
/* Variables de travail */                                
             DCL        VAR(&USR) TYPE(*CHAR) LEN(10)     
             DCL        VAR(&JOB) TYPE(*CHAR) LEN(10)     
             DCL        VAR(&NBR) TYPE(*CHAR) LEN(06)
             DCL        VAR(&EMAIL) TYPE(*CHAR) LEN(50)
             DCL        VAR(&SUJET) TYPE(*CHAR) LEN(100)
             DCL        VAR(&NOTES) TYPE(*CHAR) LEN(200)
             RTVJOBA    JOB(&JOB) USER(&USR) NBR(&NBR)    
             CHGVAR     VAR(&EMAIL) VALUE('votre@mail.fr')
             CHGVAR     VAR(&SUJET) VALUE('Enregistrement crée')
             CHGVAR     VAR(&NOTES) VALUE('Job :' +
                          *BCAT &NBR *TCAT '/' *TCAT &USR *TCAT '/' +
                          *TCAT &USR)                                    
 SNDSMTPEMM RCP((&EMAIL)) SUBJECT(&SUJET) NOTE(&NOTES) +
             CONTENT(*HTML)            
  MONMSG     MSGID(CPF0000) EXEC(GOTO CMDLBL(ERREUR))
goto fin                                                           
/* Gestion des erreurs  */                                         
erreur:                                                            
             SNDUSRMSG  MSG('Envoi email impossible pour msgint ' +
                          *bcat &job *bcat &usr *bcat &nbr ) +     
                          MSGTYPE(*INFO)                           
fin:                                                               
ENDPGM

Pour attacher votre programme et enregistrer votre trigger

 ADDPFTRG   FILE(&LIB/REP_VALID) TRGTIME(*AFTER)     
              TRGEVENT(*INSERT) PGM(&LIB/ALERT_MSG) 
              TRGLIB(&LIB)

&lib sera le nom de votre bibliothèque

En SQL ca créera un programme CEE et ca l’associera au trigger

CREATE OR REPLACE TRIGGER ALERTE_MSG                                   
 AFTER  INSERT ON REP_VALID                                            
 REFERENCING NEW AS N                                                  
 FOR EACH ROW                                                          
 MODE DB2ROW                                                           
-- email destinataire                                                  
 BEGIN                                                                 
DECLARE W_EMAIL CHAR(50);                                              
DECLARE W_SUJET CHAR(100);                                             
DECLARE W_NOTES CHAR(200);                                             
DECLARE EXIT HANDLER FOR SQLSTATE '38501'                              
 RESIGNAL SQLSTATE '38501' SET MESSAGE_TEXT = 'ENVOI MAIL IMPOSSIBLE.';
SET W_NOTES = 'Job : ' concat trim(N.REPNBR)                  
concat '/' concat trim(N.REPUSER) concat '/' concat trim(N.REPJOB) ;
SET W_EMAIL = 'votre@email.fr' ;                 
SET W_SUJET = 'Enregistrement crée' ;   
CALL QCMDEXC('SNDSMTPEMM RCP((''' concat trim(w_email) concat           
''')) SUBJECT(''' concat trim(replace(w_sujet , '''', '"'))             
concat ''') NOTE('''                                                    
concat trim(replace(W_NOTES , '''' , '"')) concat''') CONTENT(*HTML)') ;
END;

Remarques :

Dans les 2 cas si l’utilisateur n’est pas inscrit à la liste de distribution votre email ne sera pas envoyé
c’est plus simple de gérer l’erreur en CLP.
Si vous devez accéder aux données du buffer ca sera plus rapide et plus simple en SQL ici n.zone

C’est des triggers après , puisque l’information doit être écrite dans tous les cas .

/par
, Utilisation d’ACS avec le JRE OpenJ9 d’IBM

Les changements de politique d’Oracle pour Java (JRE* ou JDK*) peuvent impacter l’utilisation d’ACS* (problèmes potentiels au lancement et à l’exécution d’ACS).


Pour éviter ces problèmes, l’environnement d’exécution privilégié recommandé par IBM est IBM Semeru Runtimes. C’est une solution gratuite basée sur OpenJDK avec la JVM Open Source IBM OpenJ9.

https://www.ibm.com/support/pages/java-options-ibm-i-access-client-solutions

–

(*JRE = Java Runtime Environment

*JDK = Java Development Kit

*ACS = IBM i Access Client Solutions)

–

Téléchargement d’OpenJ9

Lien de téléchargement :

https://developer.ibm.com/languages/java/semeru-runtimes/downloads/

Choisissez la dernière version et téléchargez :

  • soit l’Installer pour Windows x64 en cliquant sur msi > pour installer OpenJ9 en tant que JRE pour Windows
  • soit le JRE zippé en cliquant sur zip > pour installer OpenJ9 en tant que JRE pour ACS seulement

–

Installation d’OpenJ9 en tant que JRE pour Windows

Si vous voulez installer OpenJ9 en tant que JRE pour Windows, exécutez l’installer :

(ici c’est l’installer ibm-semeru-open-jre_x64_windows_21.0.3_9_openj9-0.44.0.msi)

Si la version d’Oracle a été installée précédemment, après l’installation allez dans Démarrer > Programmes > Java > Configurer Java

Dans le panneau de configuration Java, allez sur l’onglet Java pour visualiser et gérer les différentes versions installées du JRE :

Si Java est déjà installé sur le poste, vous pouvez désactiver la version d’Oracle et activer la version OpenJ9 :

Il suffit de rechercher la nouvelle version pour l’ajouter, puis l’activer

–

Installation d’OpenJ9 en tant que JRE pour ACS seulement

Vous pouvez installer le JRE directement dans le répertoire \IBM\ClientSolutions\Start_Programs\Windows_x86-64.

Dans ce cas, le JRE OpenJ9 ne sera utilisé que par ACS, les autres logiciels continueront à utiliser le JRE installé sous Windows.

–

Il faudra bien lancer ACS par l’exécutable acslaunch_win-64.exe du répertoire IBM\ClientSolutions\Start_Programs\Windows_x86-64, et pas le .jar

–

Décompressez le JRE zippé que vous avez téléchargé :

–

Copiez le dossier contenu dans l’archive dans le répertoire \IBM\ClientSolutions\Start_Programs\Windows_x86-64

–

Vérification de la version du JRE utilisée par ACS

Ouvrir ACS et aller dans Aide > A propos

–

Attention

Avant de déployer le JRE d’OpenJ9 sur vos PC, il est impératif de vérifier si ACS et vos configurations de sessions 5250 fonctionnent correctement, car il peut y avoir quelques effets de bord sur certaines configurations lors du passage à OpenJ9.

/par
, , Afficher plusieurs colonnes d’enregistrements dans un sous-fichier

Contexte

Un sous-fichier nous permet d’afficher un nombre de lignes qui est limité par la taille de l’écran.
Cette taille est définie dans le script source de l’écran par le paramètre SFLPAG.

On possède un fichier que l’on souhaite afficher et qui contient plus de 19 enregistrement. Il serait donc intéressant de l’afficher sur plusieurs colonnes.

Solution

Une petite modification du script source permet de créer un sous fichier qui contient plusieurs colonnes. Il faut donc indiquer le nombre total de données que l’on souhaite voir à l’écran dans SFLPAG ainsi que le nombre de caractère qui séparent deux colonnes

La maquette se présente ainsi, le paramètre de SFLLIN correspond à l’espace (en caractères) entre deux colonnes.

En exécutant le programme, on obtient :

/par
, Prompt override program

Le programme de substitution d’invite (prompt override program) vous permet de pouvoir précharger les valeurs d’une commande afin de pouvoir modifier les paramètres existants. Comme les commandes CHGUSRPRF, CHGCMD etc…

Dans mon exemple, j’ai créé une commande CHGCLIENT afin de pouvoir modifier le libellé et le pays d’un client. Je veux que l’utilisateur saisisse le numéro du client et que ma commande récupère les valeurs actuelles. On est d’accord qu’il faudrait rajouter plus de contrôles mais c’est pour montrer le fonctionnement.

Tout d’abord il faut créer la commande en précisant le mot clé KEYPARM(*YES) sur les paramètres clé.

Ecrire ensuite le programme de récupération des données du client (CHGCLIENTO). Dans mon exemple c’est un programme RPG mais vous pouvez faire un programme CL.

Il doit recevoir en paramètres :
1. Le nom de la commande (alpha de 10)
2. Les paramètres clés (numéro client pour moi)
3. La suite des paramètres de la commande (LIBELLE et PAYS). Il faudra préciser la taille du paramètre en hexa en début de variable.

Ecrire le programme de traitement de la commande (CHGCLIENT).

Il ne vous restera plus qu’à créer votre commande en précisant le paramètre PMTOVRPGM

Exemple : CRTCMD CMD(CURLIB/CHGCLIENT) PGM(CURLIB/CHGCLIENT) TEXT(‘Modification client’) PMTOVRPGM(*CURLIB/CHGCLIENTO)

Au lancement de la commande, vous saisissez le numéro du client et les autres informations seront chargées.

/par