The structure is given by the ordering of the files in the git repo, a script copy that structure and convert md files into html.
As you said the integration in wordpress is more a mystery. They build stuff in “_build” that is obviously not commited but there must be another script that “push” the build to wordpress.
Hmm after a second look, maybe the travis and the rakefile are just to test the build because the _build folder seems to be deleted. Anyhow the files do not seems to be pushed somewhere so after travis end I guess they simply disapear.
Maybe they really use parsedown and include the php code in each page linking to the corresponding file online on github…
Après une discussion avec Mathieu, j’ai regardé plus en détail la façon dont raspberry-pi.org génère la documentation. Comme ça déjà été dit plus haut, le Rakefile sur le dépôt git sert uniquement à vérifier qu’il n’y a pas d’erreur de syntaxe dans le markdown, et vérifier les liens morts.
Il y a 2 éléments différents qui fonctionnent ensemble pour faire le site de la doc:
Il faut rendre le markdown en html. Pour ça ils utilisent parsedown (source ici et là). Le markdown est donc rendu à chaque requête http sur une page (si on excepte l’utilisation de memcache), d’où l’interêt d’utiliser parsedown que phpmarkdown car il est plus rapide.
il faut que le rendu visuel soit intégré dans le site. Pour cela, il modifient le fichier html rendu par parsedown pour :
ajouter le CSS de leur template wordpress.
ajouter le header avec la navbar
ajouter l’élément qui permet de visuellement naviguer dans les fichiers markdown (breadcrumbs)
ajouter le footer avec le lien pour modifier la contenu en markdown dans github
ajouter le footer général du site avec les liens des réseaux sociaux.
Ils ont donc très probablement simplement crée une page statique dans wordpress, et rajouté un fichier php qui fait le travail indiqué plus haut, puis configuré leur serveur web pour faire un appel au fichier php pour tout requête portant sur un fichier markdown, et ainsi rendre un fichier html parfaitement intégré dans leur site.
Ils n’ont cas ensuite à actualiser les sources markdown sur leur serveur de façon régulière avec un git pull dans un cron, ou de façon plus élégante avec un hook sur le dépôt git.
En n’y connaissant rien en php/wordpress il doit y en avoir pour 3 jours de boulot.
Cependant, avec les différents plugins utilisé sur poppy-project.org l’html généré est plutôt immonde, et ça risque de complexifier la tâche.
Ce serait à réfléchir en réunion mais je pense que ce serait une bonne idée d’uniformiser la documentation d’usage (vs doc de code générée avec sphinx propre au dépôt) des créatures poppy. Et d’intégrer les notebooks déjà réalisés soit dans ce système, soit dans la doc python générée avec sphinx en les exportant respectivement en md ou rst.
