在 Windows 上删除和重新安装 Python-Sphinx

【问题标题】：Removing and reinstalling Python-Sphinx on Windows在 Windows 上删除和重新安装 Python-Sphinx
【发布时间】：2021-02-26 20:21:39
【问题描述】：

我正在尝试使用 Python (3.8) 和 Sphinx (3.3.1) 来构建 HTML 文档。但是，sphinx-build 命令给了我以下错误：

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.

然而，

  1. build 中的 HTML 文件 kaesekuchen 未更新/更改。
  2. 文件夹c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx 不存在。

后者是我的错，因为我在文件资源管理器中删除了它，但只是因为我之前遇到了完全相同的错误，希望删除并重新安装Sphinx可以解决它。

相反，命令pip uninstall sphinx 和随后的pip install -U sphinx 不会更改该文件夹中的任何内容，尽管有以下输出，但后者只会给出以下乐观输出：

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

但文件夹c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\ 仍然不存在。

我什至尝试使用 sphinx-quickstart 从头开始​​运行一个新的 Sphinx 项目：

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.

但是尽管有这个输出，但没有创建这样的文件或source 文件夹。

如何彻底重置我的 Sphinx 安装并让我的文档再次运行？

【问题讨论】：

  • 不要将包安装到您的系统 Python 中。它只会导致痛苦和痛苦。始终创建一个虚拟环境，然后将软件包安装到该环境中。过程是（1）创建一个目录来保存你的项目，（2）cd进入那个目录，（3）python -m venv env创建虚拟环境，（4）source env/bin/activate激活虚拟环境，（5 ) env/bin/pip install Sphinx 安装 Sphinx，(6) 使用 Sphinx 快速启动。
  • @StevePiercy 只是为了补充上面的评论，我个人更喜欢在创建 venv 时使用我的 IDE (PyCharm) 接口。它更直观，允许按名称浏览 PyPI 包索引，自动升级单个包等...我从来没有花时间尝试直接在命令行上使用 pip。
  • @bad_coder 因为 OP 然而使用了命令行，所以我在这种情况下做出了回应。我自己使用 PyCharm，但我将其配置为在终端会话中禁用 activate（这是邪恶的）。您是否知道 PyCharm 通常会为您完成所有这些命令行步骤？不管平台如何，知道如何使用它们是件好事。
  • @StevePiercy 感谢您的客气话。我现在明白你为什么指出命令行步骤了。是的，我假设 PyCharm 的 UI 在后台为用户运行 pip cmds。我不知道的是关于activate 在编辑器终端中产生邪恶影响的宝贵细节——我一定会最终发现并希望在那天提醒你的明智之言。
  • FTR，我先做export VENV=/path/to/project/virtual/environment 然后$VENV/bin/pip 或任何二进制文件。虽然要输入更多内容，但它可以在我的项目的任何目录中使用。

标签： python windows pip python-sphinx


【解决方案1】：

解决这个问题需要一个有点尴尬的解释，这同时取决于：操作系统 (Windows)、您的特定安装以及您如何执行 Sphinx。

在 Windows 上，您可以在不同的地方安装多个 Python（取决于...）：

  1. 一个常用的位置是C:\Program Files\Python3x。

  2. pre-configured default path 是 C:\Users\me\AppData\Local\Programs\Python\Python3.x\。我觉得这很不方便，因为它离根很远。

目前扩展 Python 安装的流行方式是使用虚拟环境 (venv)。

  1. 您的venv，无论您决定将其放置在何处。 （使用venv 被认为是“事实上的”最佳实践。）

在某个时间点，您将PYTHONPATH 设置为environment variable on Windows，Windows 将在这些路径中查找您的Python 安装。注意Module Search Path 的规则。现在的问题是，如果您在 Path 上设置了多个 Python 安装，Windows 也会在其他安装中查找库...

（关于在 Windows 上安装 Python 的一般说明是必要的。2019 年的某个时候，Microsoft 将 Python 包含在 Windows 中 - 正如一位著名的 SO 用户 in this answer 所指出的那样，并提到了 in the documentation。大约在那个时候，有一个 Windows 错误需要使用管理员帐户设置环境变量 - 我找不到参考，但它在 SO 上的某处提到。这意味着建议您单独安装 Python 并将环境变量设置为管理员。）

话虽如此，您所描述的问题有几个方面（请特别注意您正在使用的终端）：

sphinx-build 中的第一个警告表明 Sphinx 正在尝试从您的用户帐户安装中读取文件（以上第 2 点）。问题是您正在执行sphinx-build 的终端没有权限从用户帐户安装目录中读取，因为该终端正在不同的用户帐户下运行，或者因为帐户安装路径是't set with read permission...话虽如此，请重新考虑警告：

复制静态文件...警告：无法复制 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')

警告：无法复制 html_static_file 中的文件：c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\themes\basic\static/jquery.js: PermissionError( 13, '权限被拒绝')

也可能是您从帐户安装中删除了 Sphinx，而文件/路径根本不存在。

接下来，当您尝试使用 pip 重新安装 Sphinx 时，尚不清楚它是否是 outdated cache issue，或者 pip 是否在您的 PYTHONPATH 上的另一个安装中找到 Sphinx... 可能是这种情况Sphinx 已安装并且 终端 根本没有读/写权限（取决于调用终端的用户帐户），或者该目录可能隐藏在文件资源管理器中...

如何彻底重置我的 Sphinx 安装并让我的文档再次运行？

您的 Python 基础安装（上面的第 1 点和第 2 点）只应写入系统或用户范围的更改（而不是特定项目更改）。

强烈建议您使用venv。 （如果您之前没有这样做过，那么现在是考虑这样做的合适时机，因为它是最简单、最干净的解决方案）。这最初可能看起来令人困惑，因为historically there have been several virtual-environments for Python。目前venv 是最常被引用的解决方案并且使用它很简单，您的IDE 应该有一个内置的UI 来帮助您通过几次点击来创建它。

venv 是一个 Python 环境，可扩展您的基础安装，当您必须进行特定于项目的更改时，它避免了更改基础安装的需要（例如安装了 Sphinx，理想情况下应该在 venv 而不是基础安装。）

最后，当您从 终端 运行 Sphinx 时，建议在终端上使用 activate your venv，否则执行的 Python 安装 may depend on the user account that 会调用终端。

【讨论】：

  • 感谢您提供详细信息，但据我了解，我损坏的包裹也可能发生在虚拟环境中，所以我需要补救措施吗？
  • @Marie.P.说 99% 的用户会放弃 venv 并创建一个新的可能是轻描淡写的，因为 100% 的用户会创建一个新的 venv。这就是保持基础安装干净的重点，没有人需要担心如何修复或管理软件包。您唯一担心的是pip 工作不干净，在这种情况下，您还可以创建一个新的venv 并重试...venvs 是“可丢弃”您不用担心这个有点问题。
  • 好的。我正在调查它。现在，我在创建 venv（docs.python.org/3/tutorial/venv.html，步骤 12.2）后被卡住了。我跑了activate.bat，但后来pip install sphinx声称一切都已经安装，所以环境似乎没有激活。
  • @Marie.P.试试python -m pip sphinx。或者，通常建议对 Sphinx 使用递归升级选项，也可以尝试在 pip 部分之前使用和不使用 python -m 的 pip -U sphinx。如果它不起作用，问题可能需要一些详细的分析per these rules。
  • @Marie.P.此外，如果它不起作用，我们需要有关您的确切规格的信息。请编辑问题以包含它：1）您的 Windows 版本？ 2）您是如何使用管理员和用户帐户设置环境变量的？ 3）您使用的是 IDE，哪一个？ 4) 您的终端，您是在 IDE 中运行还是从 Windows CMD 或 PowerShell 运行？ （这可能是使用罕见因素组合的极端情况。）
猜你喜欢
  • 2012-01-16
  • 1970-01-01
  • 2019-12-17
  • 2018-04-05
  • 2021-01-31
  • 1970-01-01
  • 2021-08-26
  • 1970-01-01
  • 1970-01-01
相关资源
最近更新 更多
热门标签
Java Python linux javascript Mysql C# Docker 算法 前端 SpringBoot Redis Vue spring 设计模式 .net core .net kubernetes c++ 数据库 数据结构 大数据 js 机器学习 微服务 Android Go 程序员 面试 JVM ASP.net core 云原生 人工智能 后端 PHP git CSS golang k8s Nginx Django mybatis 深度学习 多线程 React 架构 devops 爬虫 云计算 Spring Boot LeetCode