Hébergement et partage¶

La documentation est un site statique : après mkdocs build, tout le site publiable se trouve dans site. Il ne nécessite ni base de données ni serveur Python permanent.

Déploiement actuel¶

Le site bilingue est publié à l'adresse :

https://bibliotheque-vhdl-basys3.pages.dev/

Le dépôt contenant les sources reste privé. Seuls les fichiers statiques générés sont publics. Sur l'ordinateur configuré, deploy-cloudflare.cmd effectue une compilation stricte puis publie le résultat.

Option avec sources publiques : GitHub Pages¶

Pour une bibliothèque personnelle publique, GitHub Pages garde le code et le site dans le même service.

Créez un dépôt GitHub public.
Envoyez ce projet sur sa branche main.
Ouvrez Settings → Pages dans le dépôt.
Sous Build and deployment, choisissez GitHub Actions.
Dans l'onglet Actions, attendez la fin de Deploy bilingual MkDocs site.

Les liens générés sont relatifs : les deux langues fonctionnent aussi sous utilisateur.github.io/depot.

GitHub Pages est disponible pour les dépôts publics avec GitHub Free. Le site publié est public et servi en HTTPS.

Option retenue pour cette bibliothèque : Cloudflare Pages¶

Cloudflare Pages est retenu ici car il peut connecter un dépôt source privé tout en ne publiant que le site généré :

offre gratuite jusqu'à 500 compilations par mois ;
HTTPS automatique et adresse en pages.dev ;
chemins racine adaptés au sélecteur anglais/français ;
nouvelle publication automatique après chaque envoi Git ;
possibilité d'ajouter plus tard un nom de domaine personnel.

Configuration unique¶

Créez un dépôt GitHub et envoyez-y ce projet.
Dans Cloudflare, ouvrez Workers & Pages → Create application → Pages.
Sélectionnez Import an existing Git repository.
Choisissez le dépôt de documentation.
Configurez :

Paramètre	Valeur
Branche de production	`main`
Commande de compilation	`mkdocs build --strict`
Répertoire publié	`site`
Version de Python	Une version Python 3 actuellement prise en charge

Le fichier requirements.txt présent dans le projet installe MkDocs, Material et le module bilingue. Après le déploiement, Cloudflare fournit une adresse similaire à :

https://bibliotheque-vhdl-basys3.pages.dev

Chaque envoi vers main reconstruit et republie le site.

Netlify¶

Netlify permet la démonstration manuelle la plus rapide :

Construisez le site avec build-docs.cmd.
Connectez-vous à Netlify.
Déposez le répertoire site dans l'interface de déploiement.

Une adresse HTTPS publique est fournie immédiatement. Le déploiement automatique depuis Git est aussi disponible ; netlify.toml contient déjà les paramètres de compilation.

L'offre gratuite actuelle fonctionne avec des crédits mensuels et suspend les sites lorsque le quota est épuisé. Ce risque est faible pour une petite bibliothèque personnelle, mais les limites de Cloudflare Pages sont plus simples ici.

Partage hors ligne¶

Exécutez build-docs.cmd.
Compressez tout le répertoire site.
Envoyez l'archive.
Le destinataire l'extrait puis ouvre index.html.

Un véritable hébergeur statique reste préférable pour garantir le bon fonctionnement de la recherche et de la navigation.

Vérifications avant publication¶

Supprimer toute information personnelle ou confidentielle.
Exécuter mkdocs build --strict.
Tester les versions anglaise et française.
Tester le changement de langue depuis une page imbriquée.
Tester la recherche dans les deux langues.
Vérifier les modes mobile, clair et sombre.
Contrôler les licences et les liens externes.
Se rappeler que le site publié est public sauf configuration contraire.