Python-Sphinx unter Windows entfernen und neu installieren
Ich versuche, mit Python (3.8) und Sphinx (3.3.1) eine Dokumentation in HTML zu erstellen. Der sphinx-buildBefehl gibt mir jedoch den folgenden Fehler:
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.
Jedoch,
- Die HTML-Datei
kaesekucheninbuildwird nicht aktualisiert / geändert. - Der Ordner
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinxexistiert nicht.
Letzteres ist meine Schuld, weil ich es im Datei-Explorer gelöscht habe, aber nur, weil ich zuvor genau denselben Fehler Sphinxfestgestellt habe und gehofft habe, dass das Löschen und erneute Installieren ihn beheben würde.
Stattdessen ändern die Befehle pip uninstall sphinxund die nachfolgenden Befehle pip install -U sphinxnichts in diesem Ordner, und letzterer liefert trotz der folgenden Ausgabe nur die folgende optimistische Ausgabe:
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
Aber der Ordner c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\ist immer noch nicht da.
Ich habe sogar versucht, ein neues Sphinx-Projekt von Grund auf neu auszuführen 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.
Trotz dieser Ausgabe werden keine solchen Dateien oder sourceOrdner erstellt.
Was kann ich tun, um meine Sphinx-Installation sauber zurückzusetzen und meine Dokumentation erneut auszuführen?
Antworten
Um dies zu lösen, ist eine etwas umständliche Erklärung erforderlich, die gleichzeitig abhängt von: Betriebssystem (Windows), Ihrer speziellen Installation und der Ausführung von Sphinx.
Unter Windows können Sie mehrere Python-Installationen an verschiedenen Orten haben (abhängig von ...):
Ein üblicher Ort ist
C:\Program Files\Python3x.Der vorkonfigurierte Standardpfad lautet
C:\Users\me\AppData\Local\Programs\Python\Python3.x\. Ich finde das unpraktisch, weil es tief von der Wurzel entfernt ist.
Die derzeit gängige Methode zum Erweitern einer Python-Installation ist die Verwendung einer virtuellen Umgebung ( venv).
- Sie
venv, wo immer Sie sich entschieden haben, es zu platzieren. (Die Verwendung von avenvwird als "de facto" Best Practice angesehen.)
Zu einem bestimmten Zeitpunkt legen Sie unter WindowsPYTHONPATH eine Umgebungsvariable fest, und in diesen Pfaden sucht Windows nach Ihren Python-Installationen. Beachten Sie die Regeln für den Modul-Suchpfad . Das Problem besteht nun darin, dass Windows, wenn Sie mehr als eine Python-Installation in Ihrem Pfad festgelegt haben, auch in anderen Installationen nach Bibliotheken sucht ...
(Ein allgemeiner Hinweis zu Python-Installationen unter Windows ist erforderlich. Irgendwann im Jahr 2019 hat Microsoft Python in Windows aufgenommen - wie von einem bekannten SO-Benutzer in dieser Antwort angegeben und in der Dokumentation erwähnt . Zu dieser Zeit gab es einen Windows-Fehler, der Umgebungsvariablen erforderte mit dem Administratorkonto festlegen - Ich kann keine Referenz finden, diese wird jedoch irgendwo auf SO erwähnt. Dies bedeutet, dass es ratsam ist, Python separat zu installieren und Umgebungsvariablen als Administrator festzulegen.)
Das von Ihnen beschriebene Problem hat jedoch mehrere Aspekte (beachten Sie insbesondere das von Ihnen verwendete Terminal ):
Die erste Warnung in Ihrer sphinx-buildAnzeige zeigt an, dass Sphinx versucht, Dateien aus der Installation Ihres Benutzerkontos zu lesen (Punkt 2 oben). Das Problem ist, dass das Terminal, auf dem Sie ausführen, sphinx-buildkeine Berechtigung zum Lesen aus den Installationsverzeichnissen des Benutzerkontos hat, weil das Terminal unter einem anderen Benutzerkonto ausgeführt wird oder weil die Kontoinstallationspfade nicht mit Leseberechtigung festgelegt wurden sagte das, überdenken Sie die Warnungen:
Kopieren statischer Dateien ... WARNUNG: Fehler beim Kopieren einer Datei in html_static_file: c: \ Benutzer \ me \ appdata \ local \ Programme \ Python \ Python38 \ lib \ Site-Pakete \ Sphinx \ Themes \ Basic \ Static / JQuery-3.5 .1.js: PermissionError (13, 'Berechtigung verweigert')
WARNUNG: Fehler beim Kopieren einer Datei in html_static_file: c: \ Benutzer \ me \ appdata \ local \ Programme \ Python \ Python38 \ lib \ Site-Pakete \ Sphinx \ Themes \ Basic \ Static / Jquery.js: PermissionError (13, ' Erlaubnis verweigert')
Es kann auch vorkommen, dass Sie Sphinx aus Ihrer Kontoinstallation gelöscht haben und die Dateien / Pfade einfach nicht vorhanden sind.
Wenn Sie versuchen, Sphinx mithilfe von Sphinx neu zu installieren, pipist nicht ganz klar, ob es sich um ein veraltetes Cache-Problem handelt oder ob pipSphinx in einer anderen Installation auf Ihrem PYTHONPATHComputer gefunden wird. Möglicherweise ist Sphinx installiert und das Terminal hat einfach nicht gelesen / Schreibberechtigung (hängt davon ab, welches Benutzerkonto das Terminal aufgerufen hat), oder das Verzeichnis ist möglicherweise im Datei-Explorer versteckt ...
Was kann ich tun, um meine Sphinx-Installation sauber zurückzusetzen und meine Dokumentation erneut auszuführen?
Ihre Python-Basisinstallationen (Punkte 1 und 2 oben) sollten nur für system- oder benutzerweite Änderungen geschrieben werden (nicht für eine bestimmte Projektänderung).
Es wird dringend empfohlen, a zu verwenden venv. (Wenn Sie dies noch nicht getan haben, ist dies der richtige Zeitpunkt, dies in Betracht zu ziehen, da dies die einfachste und sauberste Lösung ist.) Dies mag zunächst verwirrend erscheinen, da es in der Vergangenheit mehrere virtuelle Umgebungen für Python gab . Derzeit venvist die am häufigsten genannte Lösung und ihre Verwendung ist einfach. Ihre IDE sollte über eine integrierte Benutzeroberfläche verfügen, mit deren Hilfe Sie sie mit wenigen Klicks erstellen können.
A venvist eine Python-Umgebung, die Ihre Basisinstallation erweitert. Sie vermeidet die Notwendigkeit, Ihre Basisinstallation zu ändern, wenn Sie projektspezifische Änderungen vornehmen müssen (wie die Installation von Sphinx sollte sich idealerweise auf der Basisinstallation befinden venv).
Wenn Sie Sphinx vom Terminal aus ausführen, ist es ratsam, Ihrvenv auf dem Terminal zu aktivieren. Andernfalls hängt die ausgeführte Python-Installation möglicherweise von dem Benutzerkonto ab, das das Terminal aufgerufen hat.