A partir du fichier code source main.cpp du programme principal de StockFish, on peut explorer les autres fichiers source dans l’éditeur de CodeBlocks ou dans l’aide au format Microsoft HTML Help ci-dessous.
L’HTML Help du projet a été généré pour constituer la référence du dossier de programmation du code source.
Nouveauté : comment intégrer le .chm dans l’IDE CodeBlocks pour l’aide contextuelle ?
Comment le générer à nouveau quand vous changerez le code source de SF ?
Dossier de programmation de SF au format HTML Help
StockFish.chm se présente sous la forme d’un site Web compressé dans un seul fichier comprenant :
- Introduction reprenant le markup down Source\Readme.md du site officiel,
- 270 pages HTML concernant les fonctions, classes, fichiers, etc. du code source,
- Plus de 400 schémas .svg (DOT_IMAGE_FORMAT = svg plus optimisé que .jpeg ou .png) : CLASS_GRAPH, COLLABORATION_GRAPH, GROUP_GRAPHS, UML_LOOK, CALL_GRAPH, CALLER_GRAPH. Il est recommandé d’installer au moins Microsoft Internet Explorer IE9 ou IE10 supportant SVG. Il sera utilisé par le système d’aide WinHlp32.exe même si vous avez l’habitude de Chrome ou FireFox. L’avantage de SVG est que la taille du .chm est de 1.7 MB au lieu de 11.4 MB en JPEG (c’est pire en PNG). De plus les schémas sont cliquables pour naviguer dans le graphe.
- Treeview : Namespaces, Classes, Files pour naviguer dans le code source par nom.
- "Index" de tout ce qui a été codé dans le source en entrant les premières lettres.
- La fonction "Search" nécessitera la première fois un calcul d’indexation en local.
- Code source cloné depuis Git à la date de l’article.
Afficher le .chm dans Windows
Pour afficher un fichier d’aide .hlp ou .chm dans Windows, il faut le Windows Help program WinHlp32.exe apparu pour Windows 98 et Windows XP :
- Sous Windows Vista, télécharger le Windows Help program WinHlp32.exe du patch Windows6.0-KB917607-x64.msu 611 KB du 7 mars 2007.
- Sous Windows 7, idem avec le patch Windows6.1-KB917607-x64.msu 702 KB du 14 octobre 2009.
- Sous Windows 8, idem avec le patch Windows8-RT-KB917607-x64.msu 898 KB du 26 octobre 2012.
Le .chm peut également être lu par des applications non Windows.
Attention lorsque vous visionnez le HTML Help compilé .chm, si vous ne lisez que l’arborescence dans le treeview de gauche et que la partie principale à droite est vide, vous devez débloquer une fois le .chm. Pour cela, dans le gestionnaire de fichiers de Windows, sélectionner le .chm avec le bouton droit de la souris, menu contextuel "Propriétés", "Débloquer" (Unblock) le fichier.
Afficher contextuellement le .chm dans CodeBlocks
Pour bénéficier de l’aide contextuelle dans le projet StockFish à l’intérieur de CodeBlocks, ouvrir le projet StockFish parmi la liste des projets récents au milieu de la page d’accueil :
Menu "Settings" > "Environment" >
Scroller verticalement les icônes de gauche jusqu’à "Help files" entre "HeaderFixup configuration" et "Thread search".
Click "Add" : StockFish.chm
Entre la fenêtre des "Help files" et "TIP: $(keyword) ...", il y a la zone de saisie du chemin :
"C:\Users\Chess\Documents\StockFish\Doxygen\DocStockFish.chm"
Click "OK"
Usage : ouvrir dans l’éditeur le premier fichier benchmark.cpp
Sélectionner la fonction benchmark(...)
Toutes les occurrences de benchmark sont surlignées en rose.
CodeBlocks menu "Help" > "StockFish.chm" le nouveau item qui apparaît avant "CodeBlocks".
L’HTML Help compilé de StockFish s’affiche à la page de la fonction benchmark.
Générer le .chm
Ce .chm étant relatif à une version donnée du code source, pour le générer à nouveau, il faut installer les logiciels gratuits suivants :
Télécharger doxygen-1.8.3.1-setup.exe
Installer dans C:\Users\Chess\Documents\StockFish{Doxygen\Prog
Pour les graphiques, Doxygen génère la description textuelle des schémas dans le langage DOT de GraphViz.
Télécharger graphviz-2.30.1.msi
Installer (sous Windows Vista) dans C:\Users\Chess\Documents\StockFish\Doxygen{GraphViz\Prog
Télécharger Microsoft HTML Help Workshop pour compiler et compresser les pages HTML.
Installer dans C:\Users\Chess\Documents\StockFish\Doxygen{MS HTML Help Workshop\Prog
Lancer CodeBlocks.
Cliquer sur StockFish.cbp au milieu de la page sous Recent projects.
Dans la fenêtre de gauche "Projects", sélectionner Workspace > StockFish
Menu "DoxyBlocks" > "DoxyWizard..."
Step1 : Specify the working directory from which doxygen will run
C:/Users/Chess/Documents/StockFish/Doxygen
Step2 : Configure doxygen using the Wizard and/or Expert tab, then switch to the Run tab to generate the documentation
Les options de Doxygen étant extrêmement nombreuses et parfois délicates au niveau des chemins, on se reportera au fichier texte de configuration auto-documenté que l’on peut ouvrir par le menu "File" > "Open" du DoxyWizard pour Doxygen 1.8.3.1 :
C:/Users/Chess/Documents/StockFish/Doxygen/doxyfile
Adapter les chemins (absolus et relatifs) selon votre contexte Windows du projet SF.
Après avoir sélectionné le troisième onglet "Run", cliquer sur "Run doxygen"
Les fichiers intermédiaires de compilation sont dans :
C:\Users\Chess\Documents\StockFish\Doxygen\Doc{Html
Il est conseillé d’effacer ce répertoire avant chaque regénération du .chm.
C’est pour cela que Html est sous Doc pour ne pas effacer par erreur Prog ou Setup.
Le compilateur HTML Help produira :
C:\Users\Chess\Documents\StockFish\Doxygen{Doc\StockFish.chm
