Articles

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
, , , Contrôler le nombre de paramètres passés à un programme CL – %PARMS() / CEETSTA

Contrôler le nombre de paramètres passés à un programme CL – %PARMS() / CEETSTA

Il arrive parfois d’avoir moins de paramètres passés à un programme CL que le nombre attendu, par exemple si on ajoute un paramètre à ce dernier mais que pour diverses raisons on ne souhaite pas modifier et recompiler tous les programmes qui y font appel.

Il existe deux solutions relativement simples à implémenter pour contrôler le nombre de paramètres transmis afin d’adapter en conséquence le comportement du programme : La fonction intégrée %PARMS et l’API CEETSTA.

%PARMS() – V7R4 et ultérieures

À partir de la V7R4, rien de plus simple, il suffit d’utiliser la fonction intégrée %PARMS(), qui retourne le nombre de paramètres :

PGM        PARM(&PARAM1 &PARAM2)

/* Paramètres */
DCL        VAR(&PARAM1) TYPE(*CHAR) LEN(10)
DCL        VAR(&PARAM2) TYPE(*CHAR) LEN(10)

/* Corps du programme en fonction du passage du paramètre */
IF         COND(%PARMS() *EQ 2) THEN(DO)
    SNDPGMMSG  MSG('Le paramètre &PARAM2 est renseigné')
ENDDO
ELSE       CMD(DO)
    SNDPGMMSG  MSG('Le paramètre &PARAM2 n''est pas renseigné')
ENDDO

ENDPGM

Malheureusement, si on est confrontés à une contrainte de version, %PARMS ne descend pas en dessous de la V7R4 :

CEETSTA – V7R3 et antérieures

Dans ce cas, la solution la plus propre (je ne parlerai donc pas de monitoring sur un CHGVAR) est l’utilisation de l’API CEETSTA.
Il suffit de lui passer en paramètre :
– Une variable qui contiendra la valeur de retour, 1 si le paramètre est transmis, 0 s’il n’est pas transmis
– Une variable indiquant la position du paramètre à contrôler

presence_flagSortie*INTVariable de retour : 1 ou 0
arg_numEntrée*INTPosition de la variable à tester
PGM        PARM(&PARAM1 &PARAM2)

/* Paramètres */
DCL        VAR(&PARAM1) TYPE(*CHAR) LEN(10)
DCL        VAR(&PARAM2) TYPE(*CHAR) LEN(10)

/* Déclaration des variables nécessaires à l'utilisation de l'API */
DCL        VAR(&PRESENCE) TYPE(*INT) /* Variable de retour : 1 ou 0 */
DCL        VAR(&ARG_NUM) TYPE(*INT) VALUE(2) /* Position de la variable à tester */

/* Appel de l'API */
CALLPRC    PRC('CEETSTA') PARM((&PRESENCE) (&ARG_NUM))

/* Corps du programme en fonction du passage du paramètre */
IF         COND(&PRESENCE *EQ 1) THEN(DO)
    SNDPGMMSG  MSG('Le paramètre &PARAM2 est renseigné')
ENDDO
ELSE       CMD(DO)
    SNDPGMMSG  MSG('Le paramètre &PARAM2 n''est pas renseigné')
ENDDO

ENDPGM

Remarques

Le compte des paramètres pour la arg_num commence à 1
La valeur de retour est un *INT pas un *LGL

Pour plus de détails

Documentation IBM – %PARMS() : https://www.ibm.com/docs/en/i/7.5?topic=procedure-parms-built-in-function
Documentation IBM – CEETSTA : https://www.ibm.com/docs/api/v1/content/ssw_ibm_i_75/apis/CEETSTA.htm
/par
, , , Se connecter à un serveur SSH exécuté sous Windows à partir d’un IBM i (Comment obtenir la log pour débuguer les problèmes éventuels)

Se connecter à un serveur SSH exécuté sous Windows à partir d’un IBM i (Comment obtenir la log pour débuguer les problèmes éventuels)

Mise en place d’OpenSSH Server sur Windows

Pour mettre en place OpenSSH Server sur Windows, la méthode « standard » consiste à passer par les Paramètres > Applications et fonctionnalités > fonctionnalités facultatives :

Il est recommandé de redémarrer Windows une fois la fonctionnalité ajoutée.

Il suffit ensuite de démarrer le serveur via le gestionnaire de Services Windows :

Il est également souhaitable de configurer le démarrage automatique du serveur :

Remarque

Il est également possible d’installer OpenSSH sur Windows via d’autres sources (GitHub par exemple) ce qui permet, entre autres, de choisir plus facilement sa version d’OpenSSH, voir section Détail.

Création d’un jeu de clefs SSH via ssh-keygen

Pour plus de détails sur la création de clefs, vous pouvez vous référer à l’article de Guillaume Gestion des clefs SSH.

Il est également possible d’utiliser PuttyGen, outil venant avec le client Putty pour générer le jeu de clefs de manière graphique (https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html).

Dans cet article je vais tout réaliser sur l’IBM i via QSH :

$ ssh-keygen -t ecdsa -f ~/.ssh/ssh_key

Mise en place de la clef privée et configuration côté IBM i (client)

On a généré la clef privée dans le répertoire .ssh de l’utilisateur, donc elle est déjà bien en place. Il suffit donc de créer un fichier config dans le répertoire .ssh de l’utilisateur afin de simplifier nos commandes pour la suite.
Voici un exemple de fichier config :

[~/.ssh/config]

Host windows
    Hostname sshd_server.lan
    User jl
    IdentityFile ~/.ssh/key
    StrictHostKeyChecking accept-new
HostNom de la configuration, utilisé à la place des différentes informations à la connexion
HostnameAdresse ou nom du serveur à atteindre
UserNom de l’utilisateur
IdentityFileChemin vers la clef privée
StrictHostKeyChecking accept-newPermet d’ajouter automatiquement la signature du serveur distant au known_hosts

Mise en place de la clef privée et configuration côté Windows (serveur)

Il faut transférer la clef ssh_key.pub vers Windows et l’ajouter soit au fichier %UserProfile%.ssh\authorized_keys pour un utilisateur lambda, soit au fichier C:\ProgramData\ssh\administrators_authorized_keys pour un utilisateur ayant des droits d’administrateur local.

Attention à ce niveau, les droits des fichiers sont un peu particulières, il faut comme toujours avec le SSH réduire au maximum les utilisateurs ayant accès au fichier et, particularité de Windows, ajouter le droit de lecture au profil de service local Système :

Activation du fichier de log – Configuration sshd_config

Afin de pouvoir analyser d’éventuels problèmes ou simplement vouloir observer un peu plus en détail les différentes étapes de la mise en relation d’un flux ssh il est possible d’activer la log du serveur.

Par défaut celle-ci est redirigée vers les journaux d’évènements Windows et est seulement en « info ».
On les retrouver via l’Observateur d’événements Windows :

Le mieux à mon avis est de repasser par un système plus standard, soit un vrai fichier de logs.

Pour ce faire, il faut aller modifier le fichier de configuration du serveur SSH, généralement il se trouve ici : 

C:\ProgramData\ssh\sshd_config
ou
%ProgramData%\ssh\sshd_config

Il faut rechercher les lignes suivantes :

[sshd_config]

# Logging
#SyslogFacility AUTH
#LogLevel INFO

Les décommenter et indiquer les valeurs suivantes :

[sshd_config]

# Logging
SyslogFacility LOCAL0
LogLevel Debug3

Une fois la configuration modifiée et le serveur redémarré, il suffit de retenter une connexion puis d’aller consulter le fichier de log :

C:\ProgramData\ssh\logs\sshd.log
ou
%ProgramData%\ssh\logs\sshd.log

Remarque

Les problèmes courants se passent généralement autour des lignes liées au fichier authorized_keys ou administrators_authorized_keys, problèmes de droits ou
chemin du fichier utilisé…

Test de SSH IBM i vers Windows

On peut maintenant tester le tout via QSH ou CALL QP2TERM.
Grâce au fichier config la commande est simple :
(l’option -T permet de désactiver l’allocation d’un pseudo terminal)

$ ssh -T windows
Microsoft Windows [version 10.0.19045.3208]
(c) Microsoft Corporation. Tous droits r

Il est maintenant possible d’exécuter des commandes Shell Windows à partir de cette connexion.

Si on voulait obtenir les mêmes niveaux de log côté client (IBM i) que l’on a activé côté Windows, on pourrait utiliser la commande suivante :

$ ssh -T -vvv windows
OpenSSH_8.0p1, OpenSSL 1.1.1t  7 Feb 2023                                            
debug1: Reading configuration data /home/jl/.ssh/config                              
debug1: /home/jl/.ssh/config line 1: Applying options for *                          
debug1: /home/jl/.ssh/config line 4: Applying options for laptop                     
debug1: Reading configuration data /QOpenSys/QIBM/ProdData/SC1/OpenSSH/etc/ssh_config
...
Microsoft Windows [version 10.0.19045.3208]
(c) Microsoft Corporation. Tous droits r

Pour plus de détails

OpenSSH.com : https://www.openssh.com/
OpenSSH Server sous Windows – Document Microsoft : https://learn.microsoft.com/fr-fr/windows-server/administration/openssh/openssh_overview
OpenSSH – GitHub : https://github.com/PowerShell/Win32-OpenSSH/releases
/par