diff --git a/doc/source/install/install-macos.rst b/doc/source/install/install-macos.rst new file mode 100644 index 0000000000..f3b0cf3059 --- /dev/null +++ b/doc/source/install/install-macos.rst @@ -0,0 +1,354 @@ +======================= +Installation sous macOS +======================= + +.. Attention:: + + Il y a moins de contributeurs·trices sur macOS que sur d’autres plateformes. + Il se peut que l’installation et les tests unitaires fonctionnent correctement, + partiellement ou pas du tout. Bref, en cas de problème n’hésitez pas à venir + demander de l’aide sur le `forum des Devs’ de Zeste de Savoir + `_ ! + + Les instructions ci-dessous ont été testées avec succès sur un MacBook Pro + fin-2021, avec processeur M1 Pro, sous macOS 12 (Monterey) et 13 (Ventura). + +Pour installer une version locale de ZdS sur macOS, veuillez suivre les +instructions suivantes. Si une commande ne passe pas, essayez de savoir pourquoi +avant de continuer. + +macOS étant un système UNIX proche de Linux, l’installation fonctionne quasiment +comme pour cet OS, à quelques détails près. La principale différence est que +macOS étant basé sur BSD, il faut remplacer les outils BSD par ceux de GNU (les +``gnu-coreutils``, utilisés sous Linux), et avec lesquels ``zds-site`` est conçu. + +.. note:: + + Les instructions ci-dessous sont écrites pour macOS, mais il se peut que leur + philosophie (utiliser les ``gnu-coreutils`` au lieu de ceux de BSD) permette + d’installer ``zds-site`` sur un système \*BSD. + + +Pré-requis +========== + +.. admonition:: Avis aux utilisateurs·trices avancé·es + + Ces instructions expliquent comment installer XCode, Homebrew, Python, pip, et + les utilitaires GNU, sur macOS. Si vous avez déjà : + + - une installation fonctionnelle de Homebrew et de Python 3.7+ ; + - configuré votre terminal pour utiliser les utilitaires GNU à la place de + ceux de BSD (avec `linuxify `_, + par exemple) ; + + alors vous pouvez `passer à la section suivante <#dependances-systeme>`_ + concernant l’installation de ``zds-site``. + +XCode +----- + +Pour installer ou lancer ``zds-site`` sur macOS, vous devrez utiliser un +terminal pour pouvoir y entrer des commandes servant à installer ou lancer +le site et ses composants annexes. `macOS intègre un terminal nativement +`_, +que vous pouvez utiliser. + +Pour utiliser complètement le terminal sous macOS, vous devez installer quelques +outils supplémentaires qui ne sont pas installés de base avec macOS. Depuis +votre terminal, exécutez cette commande pour les installer. + +.. sourcecode:: bash + + xcode-select --install + +Homebrew +-------- + +Vous aurez ensuite besoin d’**Homebrew**, un système permettant de télécharger et +d’installer des logiciels sous macOS depuis la ligne de commande, et de les +mettre à jour. Nous nous en servirons pour installer Python (si nécessaire) et +les dépendances de ``zds-site``. + +`Les instructions d’installation d’Homebrew sont sur leur site web `_. + +Python 3 +-------- + +``zds-site`` dépend d’une version récente de Python 3. Sous macOS Ventura et plus +récent (macOS 13+), Python 3 est installé avec XCode, qu’on a installé plus haut. +Pour vérifier, exécutez la commande suivante : + +.. sourcecode:: bash + + python --version + +Si vous obtenez une version inférieure à Python 3.7 (et notamment si vous voyez +``Python 2.7``), il vous faudra installer une version récente de Python avec +Homebrew. Sinon, vous pouvez utiliser la version intégrée avec macOS de Python, +mais vous devrez installer ``pip``. + +Si votre version de Python est trop vieille +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Il vous faut installer Python avec Homebrew. Exécutez dans un terminal : + +.. sourcecode:: bash + + brew install python + +Puis revérifiez la version de Python avec ``python --version``. Si elle n’a pas +changé, tentez de redémarrer votre terminal. + +Si vous gardez la version native de Python +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Si vous avez décidé de garder la version native de Python, si elle est assez récente, +vous allez quand même devoir installer ``pip``, un logiciel compagnon de Python +servant à installer des bibliothèques externes en Python — des extensions +permettant d’augmenter ses possibilités facilement. + +Pour vérifier que vous disposez de ``pip``, exécutez l’une de ces commandes : + +.. sourcecode:: bash + + pip --version # ou + pip3 --version # ou + python -m pip --version + +Vous devriez obtenir un numéro de version de pip et de Python, comme cela : + +.. sourcecode:: bash + + $ pip --version # ou une des autres commandes + pip 22.3.1 from /opt/homebrew/lib/python3.10/site-packages/pip (python 3.10) + +Si ces commandes retournent toutes une erreur, et non un numéro de version, +vous devez installer ``pip``. `Les instructions d’installation sont sur le site +web de pip. `_ + +Utilitaires GNU/Linux au lieu de BSD +------------------------------------ + +``zds-site`` est conçu pour fonctionner avec les utilitaires de Linux (les +``gnu-coreutils``), différents des utilitaires natifs de \*BSD (et donc de macOS, +qui en est un lointain descendant). + +Le plus simple est le projet ``linuxify``, qui installe toutes les versions GNU +de divers logiciels avec Homebrew. Par défaut, ces versions viennent préfixées, +pour ne pas entrer en conflit avec les versions du système. En pratique, ce n’est +pas un problème d’utiliser dans votre environnement local les versions de GNU, +donc vous pouvez utiliser en permanence ces versions à la place de celles de BSD. + +Dans le doute, remplacez en permanence par les versions de GNU : c’est sans impact +négatif et ça permet à ``zds-site`` de fonctionner sans manipulation particulière. + +`Commencez par installer linuxify `_, +tel que précisé sur leur site. Si vous avez une erreur disant ``command not found: git``, +exécutez dans votre terminal la commande ``brew install git``. + +Lorsqu’il vous demande *Do you want to change your shell to the latest bash*, +répondez non (``n``). + +Ensuite, si vous choisissez de remplacer en permanence les utilitaires BSD par +ceux de GNU, exécutez la commande suivante pour automatiquement utiliser les +utilitaires GNU quand vous utilisez votre terminal, puis redémarrez votre terminal. + +.. sourcecode:: bash + + echo ". ~/.linuxify" >> ~/.zshrc + +Si vous choisissez de ne **pas** le faire, alors il vous faudra exécuter cette +commande dans *chaque* terminal où vous exécuterez des commandes d’installation +ou de mise à jour de ``zds-site`` (une fois par terminal, pas besoin de la +ré-exécuter à chaque fois) : + +.. sourcecode:: bash + + . ~/.linuxify + + +Dépendances système +=================== + +Le script d’installation n’installant pas encore les paquets automatiquement sur +macOS, vous devez le faire à la main, via Homebrew. Exécutez la commande +suivante pour tout installer. + +.. sourcecode:: bash + + brew install curl gettext cairo + + +Une fois les pré-requis terminés, vous pouvez vous lancer dans l‘installation +de l’environnement de ``zds-site``. + + +Installation de ``zds-site`` +============================ + +Commencez par cloner le dépôt de ``zds-site``, ou idéalement, votre fork sur +lequel vous travaillerez avant d’envoyer des *Pull-Requests*. + +.. sourcecode:: bash + + git clone git@github.com:VOTRE-PSEUDO-GITHUB/zds-site.git + cd zds-site + +``zds-site`` peut s’installer de deux façons : + +- une version minimale, qui ne contient que le site lui-même, mais pas le moteur + de recherche ni le système d’export des PDF ; +- une version complète, qui contient tout, et qui est aussi plus lourde à + installer. + +.. Attention:: + + La version complète **ne peut être automatiquement installée pour le moment** + car l’installeur télécharge une version de Java (pour ElasticSearch) spécifique + à Linux. Cependant, vous pouvez remplacer la version de Java installée dans + ``zds-site/zdsenv/lib/jdk`` par une version fonctionnant sous macOS et ElasticSearch + fonctionnera. + + Le système de génération et d’export des PDF devrait fonctionner normalement. + + La version minimale a été testée avec succès. + +.. seealso:: + + - `Installation d’Elasticsearch `_ ; + - `installation de LaTeX `_. + +Pour installer la version minimale, exécutez depuis la racine du dépôt que vous +venez de cloner : + +.. sourcecode:: bash + + ./scripts/install_zds.sh +base -packages + +Si vous voulez la version complète : + +.. sourcecode:: bash + + ./scripts/install_zds.sh +full -packages + +.. note:: + + L’option ``-packages`` désactive l’installation automatique des dépendances + système, qui n’est pour le moment supportée que sous Linux. + +.. note:: + + Vous pouvez relire le script avant de l’exécuter pour savoir ce qu’il fait. + Mais dans l’idée, ce script va : + + - installer ``virtualenv`` (via ``pip``), un logiciel Python permettant de + créer des environnements virtuels cloisonnés en Python ; + - créer un environnement virtuel dans le sous-dossier ``zdsenv`` ; + - installer dans votre dossier utilisateur le logiciel ``nvm`` (*Node Versions + Manager*), un outil permettant d’installer différentes versions de NodeJS ; + - installer la bonne version de NodeJS localement (uniquement pour ``zds-site``) + et intégrer le chargement de la cette bonne version à l’environnement virtuel ; + - installer les dépendances de ``zds-site`` dans l’environnement virtuel ; + - installer ``zmarkdown``, le moteur de rendu Markdown utilisé par ``zds-site`` ; + - installer les dépendances du *front-end* avec ``npm`` puis compiler le + *font-end* ; + - créer la base de données utilisée par ``zds-site`` (avec SQLite) et la + remplir de données de test ; + - intégrer au dépôt local un *pre-commit hook* `vérifiant que le code Python + est correctement formaté à chaque commit <../utils/git-pre-hook.html>`_ + (et le formatant le cas échéant). + + Si vous installez la version complète, le script va, en plus : + + - installer une version de Java pour Linux dans le dossier ``zds-site/zdsenv/lib/jdk`` + et modifier l’environnement virtuel pour que cette version de Java soit utilisée ; + - installer ElasticSearch dans le dossier ``zds-site/.local/elasticsearch`` ; + - installer TeXLive (permettant de compiler du LaTeX en PDF, utilisé pour les + exports PDF) dans le dossier ``zds-site/.local/texlive`` ; + - cloner le dépôt contenant le modèle LaTeX utilisé par l’export PDF dans le + dossier ``zds-site/latex-template``. + + +Lancement de ``zds-site`` +========================= + +Une fois dans votre environnement Python et toutes les dépendances installées, +lançons ZdS. + +Il faut d’abord lancer ``zmarkdown``, le moteur de rendu Markdown utilisé par +Zeste de Savoir. Ce moteur fonctionne sur un modèle client-serveur : ``zds-site`` +envoie une requête HTTP (en local) pour obtenir le rendu d’un document Markdown +en HTML, ePub, ou LaTeX. Il faut donc démarrer le serveur ``zmarkdown`` en +arrière-plan. + +Ensuite, on démarre ``zds-site``. + +.. sourcecode:: bash + + # Depuis la racine du dépôt zds-site + make zmd-start + make run + +Le démarrage de ``zds-site`` entraîne celui du *backend* Python dans un mode +optimisé pour le développement. Notamment, le cache est totalement désactivé +et des outils de débogage rendent disponible plein d’informations sur chaque +page, les données techniques envoyées (paramètres de templates, …) et les +requêtes SQL envoyées. Ces outils sont pratiques mais ils peuvent être lourds. +Si vous avez une machine peu puissante et que vous voulez une version plus légère, +mais sans tous ces outils de développement, vous pouvez démarrer une version +plus légère de ``zds-site`` ainsi. + +.. sourcecode:: bash + + make run-fast + +Ces deux façons de lancer ``zds-site`` lancent aussi la compilation automatique +à la moindre modification des fichiers du *front-end* (SCSS, JS, etc.). Si vous +voulez également désactiver cela, car vous ne travaillez pas sur le *front-end* +et/ou que vous voulez une version plus légère du site, vous pouvez ne lancer que +le *back-end* : + +.. sourcecode:: bash + + make run-back # ou (cf. plus haut) + make run-back-fast + +Pour lister toutes les options disponibles, exécutez simplement, sans argument : + +.. sourcecode:: bash + + make + +Données de test +=============== + +L’installeur a créé pour nous le `jeu de données utile au développement +<../utils/fixture_loaders.html>`_. Si pour une raison ou pour une autre, vous +voulez repartir de zéro en écrasant toutes les données de votre installation +locale, vous pouvez le faire. + +.. warning:: + + Cette commande **supprime totalement votre base de données, ainsi que tous les + contenus que vous avez pu créer, sur votre instance locale**, puis recrée des + données de test aléatoires à partir de zéro. + + **Il n’est pas possible d’annuler cette opération.** + +.. sourcecode:: bash + + make new-db + +Mettre à jour votre instance locale +=================================== + +Pour rapidement mettre votre instance locale à jour, par exemple pour tester une +*Pull-Request* ou si vous vous êtes mis à jour depuis le dépôt principal, lancez : + +.. sourcecode:: bash + + make update + +Cette commande va mettre à jour le *back-end* et le *front-end*, puis migrer la +base de données (si nécessaire) et recompiler le *front-end*. diff --git a/doc/source/install/install-osx.rst b/doc/source/install/install-osx.rst deleted file mode 100644 index c59c0a51e6..0000000000 --- a/doc/source/install/install-osx.rst +++ /dev/null @@ -1,119 +0,0 @@ -======================= -Installation sous macOS -======================= - -.. Attention:: - - Cette partie de la documentation n'est probablement pas à jour faute de contributeur utilisant MacOS. Il se peut que l'installation et les tests unitaires fonctionnent correctement, partiellement ou pas du tout. Bref, en cas de problème n'hésitez pas à venir demander de l'aide sur le `forum des Devs' de Zeste de Savoir `_ ! - -Pour installer une version locale de ZdS sur macOS, veuillez suivre les instructions suivantes. -Si une commande ne passe pas, essayez de savoir pourquoi avant de continuer. - -Pré-requis -========== - -- Installer XCode : - -.. sourcecode:: bash - - xcode-select --install - -- Installer `Homebrew `_. -- Installer un nouveau Python par Homebrew : - -.. sourcecode:: bash - - brew install python --framework - # Il se peut que votre système n'utilise pas la nouvelle version de Python. Si c'est le cas, lancez la commande suivante. - export PATH=/usr/local/bin:/usr/local/sbin:${PATH} - -- Si vous avez décidé de ne pas installer un nouveau python et que vous utilisez celui de base du système, installez pip : - -.. sourcecode:: bash - - wget https://bootstrap.pypa.io/get-pip.py - python3 get-pip.py - -- Installer toutes les dépendances systèmes nécessaires : - -.. sourcecode:: bash - - brew install gettext cairo --without-x11 py2cairo node && \ - pip3 install virtualenv virtualenvwrapper - -Une fois les pré-requis terminés, vous pouvez vous lancer dans l'installaton de l'environnement de zds. - -Configuration de virtualenv -=========================== - -(Si vous n'utilisez pas bash mais un autre shell, par exemple zsh, remplacez ``~/.bash_profile`` par le fichier rc de votre shell, par exemple ``~/.zshrc``.) - -.. sourcecode:: bash - - mkdir ~/.virtualenvs - echo "export WORKON_HOME=$HOME/.virtualenvs" >> ~/.bash_profile - echo "source /usr/local/Cellar/python3/3*/Frameworks/Python.framework/Versions/3.*/bin/virtualenvwrapper.sh" >> ~/.bash_profile - source ~/.bash_profile - -Usage de virtualenv -=================== - -Création d'un virtualenv : - -.. sourcecode:: bash - - mkvirtualenv -p python3 zdsenv - -Lancer un virtualenv : - -.. sourcecode:: bash - - workon zdsenv - -Quitter un virtualenv : - -.. sourcecode:: bash - - deactivate - - -Installation des des dépendances front et back -============================================== - -On installe `les outils du front-end `_, `zmarkdown `_ puis les packages python: - -.. sourcecode:: bash - - make install-front - make build-front - make zmd-install - make install-back - -Lancer ZdS -========== - -Une fois dans votre environnement python et toutes les dépendances installées, lançons ZdS. -On crée d'abord la base de donnée, puis le `jeu de données utile au développement <../utils/fixture_loaders.html>`_: - -.. sourcecode:: bash - - make migrate-db - make generate-fixtures - -On peut finalement lancer zmarkdown, puis ZdS: - -.. sourcecode:: bash - - make zmd-start - make run-back - - -Aller plus loin -=============== - -Pour faire fonctionner ZdS dans son ensemble vous devez installer les outils LateX et Elasticsearch: - -- `Installez Elasticsearch `_ ; -- `Installez LaTeX `_. - -Vous pouvez également `indiquer à Git de ne pas effectuer de commit s'il y a des erreurs de formatage dans le code <../utils/git-pre-hook.html>`__.