Sphinx

Qu’est-ce que Sphinx ?

Sphinx est un utilitaire qui a pour rôle de convertir du markdown, ou tout autre style de documentation « technique » en page web.

Installation

J’ai installé sphinx à travers l’utilisateur jenkins, comme c’est principalement lui qui va mettre à jour mes pages de documentations. Pour le coup, on est obligé de se servir du su - (et donc d’être root à la base ou d’avoir mis un mot de passe au compte jenkins, ce qui n’est pas bien).

su - jenkins
python3 -m venv .local/docs
source /var/lib/jenkins/.local/docs/bin/activate
pip install sphinx myst_parser m2r2 sphinx-pdj-theme

Mise à jour

su - jenkins
source /var/lib/jenkins/.local/docs/bin/activate
pip3 list -o | cut -f1 -d' ' | tr " " "\n" | awk '{if(NR>=3)print}' | cut -d' ' -f1 | xargs -n1 pip3 install -U

Attention quand tu fais ça !! M2R2 ne gère pas la nouvelle version de mistune. Il faut la fixer :

pip uninstall mistune
pip install mistune==0.8.4

Configuration

Sécurisation

Utilisation

Le job

Mon intérêt dans l’utilisation de Sphinx est d’automatiser la mise à jour de mon site web de tutoriel. Pour cela, je veux qu’il s’appuie sur mes commits git. Donc, j’ai créé un job dans jenkins pour cela :

Gestion de code source :
git
Repository URL : https://git.luclis.fr/Lucas.FILIPPI/Hacking.git/
Credential : jenkins
Branch */master
Ce qui déclenche le build
scrutation de l'outil de gestion de version: H/5 * * * *

Le script

Une fois le job créer, il faut préciser le script que je vais utiliser.

# Definition des variables
## Definition du nom du repo Git. Croyez-le, 'y'a pas de variable d'environnement pour ça.
nb_slash=`echo "/$GIT_URL" |grep -o "A" |wc -l` #On rajoute un / au debut car cut commence a 1.
git_name=`echo $GIT_URL | cut -d "/" -f $nb_slash- | sed -e 's/\.git//'`
git_branchname=`echo $GIT_BRANCH | cut -d "/" -f 2`

dest_src=$WORKSPACE
dest_html=/var/www/docs/$git_name/$BRANCH_NAME/
jenkins_home=/var/lib/jenkins
theme=sphinx_pdj_theme
year=`date +%Y`

#Petit cleanup
rm -Rf ${dest_src}/{.git,.github}
# On verifie que le dossier est bien creer.
mkdir -p $dest_html
# On creer la configuration de sphinx
cat > $dest_src/conf.py<<EOF
# Configuration file for the Sphinx documentation builder.
project = "$git_name"
copyright = "${year}, @Luclis"
author = "$GIT_AUTHOR"
release = '2'

extensions = ['myst_parser','${theme}']
templates_path = ['_templates']
exclude_patterns = []
language = 'fr'
html_theme = '${theme}'
html_static_path = ['_static']
EOF

# Peuplement du fichier index.rst
${jenkins_home}/.local/docs/bin/m2r2 ${dest_src}/README.md  --overwrite
parent_dirs=`find ${dest_src}/ -maxdepth 1 -type d -path "${dest_src}/[a-zA-Z0-9]*" -printf "%f\\n"`
echo "\\n.. toctree::\\n   :maxdepth: 3\\n\\n" >> ${dest_src}/README.rst
# Peuplement des autres fichiers
for parent in $parent_dirs ; do
    echo "   ${parent}" >> ${dest_src}/README.rst
    echo "## ${parent}\\n\\n.. toctree::\\n   :maxdepth: 1" > ${dest_src}/${parent}.md
    ${jenkins_home}/.local/docs/bin/m2r2 ${dest_src}/${parent}.md  --overwrite
    rm ${dest_src}/${parent}.md
    top_child_dirs=`tree  -diI "*\.d" ${dest_src}/${parent} | head -n -2` #Affiche les dossiers
    # On boucle sur les répertoires en dessous le parent
    for child in $top_child_dirs; do
        if [ "${dest_src}/${parent}" = "${child}" ]; then
            echo "\\n \n${parent}\\n===============\\n.. toctree::\\n   :maxdepth: 1\\n" > ${dest_src}/${parent}.rst
            find ${dest_src}/${parent} -maxdepth 1 -type f -name "*.md" -printf "\\n   ${parent}/%P" >> ${dest_src}/${parent}.rst
        else
            echo "\\n \n${child}\\n----------------\\n.. toctree::\\n   :maxdepth: 1\\n" >> ${dest_src}/${parent}.rst
            find ${dest_src}/${parent}/${child} -maxdepth 1 -type f -name "*.md" -printf "\\n   ${parent}/${child}/%P" |sort >> ${dest_src}/${parent}.rst #Je ne gère pas les dossiers imbriqués là ! ...
        fi
    done
done

# Renommage du fichier et exécution du builder
mv ${dest_src}/README.rst ${dest_src}/index.rst
${jenkins_home}/.local/docs/bin/sphinx-build -b html ${dest_src} ${dest_html}

TroubleShooting