Suppression et réinstallation de Python-Sphinx sous Windows
J'essaye d'utiliser Python (3.8) et Sphinx (3.3.1) pour construire une documentation en HTML. Cependant, la sphinx-buildcommande me donne l'erreur suivante:
C:\Users\Me\Dropbox\Kuchen>sphinx-build -b html source build
Running Sphinx v3.3.1
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 0 added, 1 changed, 0 removed
reading sources... [100%] kaesekuchen
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] kaesekuchen
generating indices... genindex done
writing additional pages... search done
copying static files... WARNING: Failed to copy a file in html_static_file: c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\themes\basic\static/jquery-3.5.1.js: PermissionError(13, 'Permission denied')
WARNING: Failed to copy a file in html_static_file: c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\themes\basic\static/jquery.js: PermissionError(13, 'Permission denied')
done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded, 2 warnings.
cependant,
- Le fichier HTML
kaesekuchenenbuildest pas mis à jour / modifié. - Le dossier
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinxn'existe pas.
Ce dernier est de ma faute, car je l'ai supprimé dans l'explorateur de fichiers, mais uniquement parce que j'ai rencontré exactement la même erreur auparavant, et j'espérais que la suppression et la réinstallation Sphinxle résoudraient.
Au lieu de cela, les commandes pip uninstall sphinxet les suivantes pip install -U sphinxne changent rien dans ce dossier, et ce dernier ne donne que la sortie optimiste suivante malgré la sortie suivante:
Microsoft Windows [Version 10.0.18363.1198]
(c) 2019 Microsoft Corporation. All rights reserved.
C:\Users\me>pip uninstall sphinx
Found existing installation: Sphinx 3.3.1
Uninstalling Sphinx-3.3.1:
Would remove:
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx-3.3.1.dist-info\*
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\*
c:\users\me\appdata\local\programs\python\python38\scripts\sphinx-apidoc.exe
c:\users\me\appdata\local\programs\python\python38\scripts\sphinx-autogen.exe
c:\users\me\appdata\local\programs\python\python38\scripts\sphinx-build.exe
c:\users\me\appdata\local\programs\python\python38\scripts\sphinx-quickstart.exe
Proceed (y/n)? y
Successfully uninstalled Sphinx-3.3.1
C:\Users\me>pip install -U sphinx
Collecting sphinx
Using cached Sphinx-3.3.1-py3-none-any.whl (2.9 MB)
Requirement already satisfied, skipping upgrade: docutils>=0.12 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (0.16)
Requirement already satisfied, skipping upgrade: sphinxcontrib-serializinghtml in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.1.4)
Requirement already satisfied, skipping upgrade: snowballstemmer>=1.1 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (2.0.0)
Requirement already satisfied, skipping upgrade: alabaster<0.8,>=0.7 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (0.7.12)
Requirement already satisfied, skipping upgrade: setuptools in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (41.2.0)
Requirement already satisfied, skipping upgrade: colorama>=0.3.5; sys_platform == "win32" in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (0.4.4)
Requirement already satisfied, skipping upgrade: sphinxcontrib-jsmath in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.0.1)
Requirement already satisfied, skipping upgrade: babel>=1.3 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (2.9.0)
Requirement already satisfied, skipping upgrade: imagesize in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.2.0)
Requirement already satisfied, skipping upgrade: sphinxcontrib-devhelp in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.0.2)
Requirement already satisfied, skipping upgrade: sphinxcontrib-qthelp in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.0.3)
Requirement already satisfied, skipping upgrade: Jinja2>=2.3 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (2.11.2)
Requirement already satisfied, skipping upgrade: sphinxcontrib-applehelp in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.0.2)
Requirement already satisfied, skipping upgrade: requests>=2.5.0 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (2.25.0)
Requirement already satisfied, skipping upgrade: packaging in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (20.4)
Requirement already satisfied, skipping upgrade: sphinxcontrib-htmlhelp in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (1.0.3)
Requirement already satisfied, skipping upgrade: Pygments>=2.0 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from sphinx) (2.7.2)
Requirement already satisfied, skipping upgrade: pytz>=2015.7 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from babel>=1.3->sphinx) (2020.4)
Requirement already satisfied, skipping upgrade: MarkupSafe>=0.23 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from Jinja2>=2.3->sphinx) (1.1.1)
Requirement already satisfied, skipping upgrade: urllib3<1.27,>=1.21.1 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from requests>=2.5.0->sphinx) (1.26.2)
Requirement already satisfied, skipping upgrade: idna<3,>=2.5 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from requests>=2.5.0->sphinx) (2.10)
Requirement already satisfied, skipping upgrade: certifi>=2017.4.17 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from requests>=2.5.0->sphinx) (2020.11.8)
Requirement already satisfied, skipping upgrade: chardet<4,>=3.0.2 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from requests>=2.5.0->sphinx) (3.0.4)
Requirement already satisfied, skipping upgrade: six in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from packaging->sphinx) (1.15.0)
Requirement already satisfied, skipping upgrade: pyparsing>=2.0.2 in c:\users\me\appdata\local\programs\python\python38\lib\site-packages (from packaging->sphinx) (2.4.7)
Installing collected packages: sphinx
Successfully installed sphinx-3.3.1
Mais le dossier c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\n'est toujours pas là.
J'ai même essayé de lancer un nouveau projet Sphinx à partir de zéro, en utilisant sphinx-quickstart:
For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: en
Creating file C:\Users\me\Dropbox\Kuchentest\source\conf.py.
Creating file C:\Users\me\Dropbox\Kuchentest\source\index.rst.
Creating file C:\Users\me\Dropbox\Kuchentest\Makefile.
Creating file C:\Users\me\Dropbox\Kuchentest\make.bat.
Finished: An initial directory structure has been created.
You should now populate your master file C:\Users\me\Dropbox\Kuchentest\source\index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.
Mais malgré cette sortie, aucun fichier ou sourcedossier n'est créé.
Que puis-je faire pour réinitialiser proprement mon installation Sphinx et que ma documentation s'exécute à nouveau?
Réponses
Résoudre ce problème nécessite une explication quelque peu maladroite qui dépend simultanément: du système d'exploitation (Windows), de votre installation particulière et de la manière dont vous exécutez Sphinx.
Sous Windows, vous pouvez avoir plusieurs installations Python à différents endroits (selon ...):
Un emplacement habituel est
C:\Program Files\Python3x.Le chemin par défaut préconfiguré est
C:\Users\me\AppData\Local\Programs\Python\Python3.x\. Je trouve cela gênant car il est situé loin de la racine.
La manière actuellement courante d'étendre une installation Python consiste à utiliser un environnement virtuel ( venv).
- Votre
venv, où que vous ayez décidé de le placer. (L'utilisation de avenvest considérée comme la meilleure pratique "de facto" .)
À un moment donné, vous définissez PYTHONPATHcomme une variable d'environnement sur Windows et c'est dans ces chemins que Windows recherchera vos installations Python. Notez les règles du chemin de recherche du module . Le problème devient maintenant que si vous avez plus d'une installation Python définie sur votre chemin, Windows recherchera également des bibliothèques dans d'autres installations ...
(Une note générale sur les installations de Python sur Windows est nécessaire. À un moment donné, en 2019, Microsoft a inclus Python avec Windows - comme indiqué par un utilisateur SO de premier plan dans cette réponse , et référencé dans la documentation . À cette époque, il y avait un bogue Windows qui nécessitait des variables d'environnement à définir avec le compte administrateur - je ne trouve pas de référence mais elle est mentionnée quelque part sur SO. Cela signifie qu'il est conseillé de faire votre installation séparée de Python et de définir les variables d'environnement en tant qu'admin.)
Cela dit, le problème que vous décrivez a plusieurs aspects ( faites particulièrement attention au terminal que vous utilisez):
Le premier avertissement dans votre sphinx-buildindique que Sphinx essaie de lire des fichiers depuis l'installation de votre compte utilisateur (point 2 ci-dessus). Le problème est que le terminal sur lequel vous exécutez sphinx-buildn'a pas l'autorisation de lire les répertoires d'installation du compte utilisateur, car le terminal est exécuté sous un autre compte utilisateur ou parce que les chemins d'installation du compte ne sont pas définis avec l'autorisation de lecture ... dit cela, reconsidérez les avertissements:
copie de fichiers statiques ... AVERTISSEMENT: échec de la copie d'un fichier dans html_static_file: c: \ users \ me \ appdata \ local \ programmes \ python \ python38 \ lib \ site-packages \ sphinx \ themes \ basic \ static / jquery-3.5 .1.js: PermissionError (13, 'Autorisation refusée')
AVERTISSEMENT: échec de la copie d'un fichier dans html_static_file: c: \ users \ me \ appdata \ local \ programs \ python \ python38 \ lib \ site-packages \ sphinx \ themes \ basic \ static / jquery.js: PermissionError (13, ' Permission refusée')
Il se peut également que vous ayez supprimé Sphinx de l'installation de votre compte et que les fichiers / chemins ne soient tout simplement pas là.
Ensuite, lorsque vous essayez de réinstaller Sphinx en utilisant, pipil n'est pas tout à fait clair s'il s'agit d'un problème de cache obsolète , ou si vous piptrouvez Sphinx dans une autre installation sur votre PYTHONPATH... Il se peut que Sphinx soit installé et que le terminal n'ait tout simplement pas lu / autorisation d'écriture (dépend du compte utilisateur qui a appelé le terminal), ou le répertoire peut être caché dans l'explorateur de fichiers ...
Que puis-je faire pour réinitialiser proprement mon installation Sphinx et que ma documentation s'exécute à nouveau?
Vos installations de base Python (points 1 et 2 ci-dessus) ne sont censées être écrites que pour les modifications du système ou de l'utilisateur (pas pour un changement de projet particulier).
Il est fortement recommandé d'utiliser un fichier venv. (Si vous ne l'avez pas encore fait, ce serait le bon moment pour envisager de le faire car c'est la solution la plus simple et la plus propre). Cela peut sembler déroutant au départ car il existe historiquement plusieurs environnements virtuels pour Python . Actuellement, venvc'est la solution la plus fréquemment citée et son utilisation est simple, votre IDE devrait avoir une interface utilisateur intégrée pour vous aider à la créer en quelques clics.
A venvest un environnement Python qui étend votre installation de base, il évite d'avoir à changer votre installation de base lorsque vous devez apporter des modifications spécifiques au projet (comme l'installation de Sphinx, devrait idéalement être sur l' venvinstallation et non sur l'installation de base.)
Enfin, lorsque vous exécutez Sphinx depuis le terminal, il est conseillé de l' activervenv sur le terminal, sinon l'installation Python qui est exécutée peut dépendre du compte utilisateur qui a appelé le terminal.