Xóa và cài đặt lại Python-Sphinx trên Windows
Tôi đang cố gắng sử dụng Python (3.8) và Sphinx (3.3.1) để tạo tài liệu bằng HTML. Tuy nhiên, sphinx-buildlệnh cho tôi lỗi sau:
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.
Tuy nhiên,
- Tệp HTML
kaesekuchentrongbuildkhông được cập nhật / thay đổi. - Thư mục
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinxkhông tồn tại.
Lỗi thứ hai là lỗi của tôi, vì tôi đã xóa nó trong trình khám phá tệp, nhưng chỉ vì tôi gặp phải lỗi chính xác trước đó và hy vọng rằng việc xóa và cài đặt Sphinxlại sẽ giải quyết được nó.
Thay vào đó, các lệnh pip uninstall sphinxvà lệnh tiếp theo pip install -U sphinxkhông thay đổi bất kỳ điều gì trong thư mục đó và lệnh sau chỉ cung cấp đầu ra lạc quan sau mặc dù đầu ra sau:
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
Nhưng thư mục c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\vẫn không ở đó.
Tôi thậm chí đã cố gắng chạy một dự án Sphinx mới từ đầu, sử dụng 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.
Nhưng bất chấp đầu ra này, không có tệp hoặc sourcethư mục nào được tạo.
Tôi có thể làm gì để đặt lại hoàn toàn cài đặt Sphinx của mình và chạy lại tài liệu của mình?
Trả lời
Giải quyết vấn đề này đòi hỏi một lời giải thích hơi khó xử đồng thời phụ thuộc vào: hệ điều hành (Windows), cài đặt cụ thể của bạn và cách bạn đang thực thi Sphinx.
Trên Windows, bạn có thể có một số cài đặt Python ở những nơi khác nhau (tùy thuộc vào ...):
Một vị trí thông thường là
C:\Program Files\Python3x.Các đường dẫn mặc định được cấu hình sẵn là
C:\Users\me\AppData\Local\Programs\Python\Python3.x\. Tôi thấy điều này bất tiện vì nó nằm cách xa gốc.
Cách phổ biến hiện nay để mở rộng cài đặt Python là sử dụng môi trường ảo ( venv).
- Của bạn
venv, bất cứ nơi nào bạn quyết định đặt nó. (Sử dụng avenvđược coi là phương pháp hay nhất "trên thực tế" .)
Tại một thời điểm, bạn đặt PYTHONPATHlàm biến môi trường trên Windows và chính trong các đường dẫn đó, Windows sẽ tìm kiếm các bản cài đặt Python của bạn. Lưu ý các quy tắc cho Đường dẫn Tìm kiếm Mô-đun . Vấn đề bây giờ là nếu bạn có nhiều hơn một cài đặt Python được đặt trên Đường dẫn của mình, Windows cũng sẽ tìm kiếm các thư viện trong các cài đặt khác ...
(Lưu ý chung về việc cài đặt Python trên Windows là cần thiết. Vào năm 2019, Microsoft đã đưa Python vào Windows - theo ghi nhận của một người dùng SO nổi tiếng trong câu trả lời này và được tham khảo trong tài liệu . Khoảng thời gian đó, có một lỗi Windows yêu cầu các biến môi trường được đặt bằng tài khoản quản trị viên - Tôi không thể tìm thấy tài liệu tham khảo nhưng nó được đề cập ở đâu đó trên SO. Có nghĩa là bạn nên thực hiện cài đặt riêng Python và đặt các biến môi trường làm quản trị viên.)
Phải nói rằng, vấn đề bạn đang mô tả có một số khía cạnh (hãy lưu ý đặc biệt về thiết bị đầu cuối bạn đang sử dụng):
Cảnh báo đầu tiên của bạn sphinx-buildcho biết Sphinx đang cố gắng đọc các tệp từ cài đặt tài khoản người dùng của bạn (điểm 2 ở trên). Vấn đề là thiết bị đầu cuối nơi bạn đang thực thi sphinx-buildkhông có quyền đọc từ các thư mục cài đặt tài khoản người dùng, vì thiết bị đầu cuối đang được chạy trong một tài khoản người dùng khác hoặc do đường dẫn cài đặt tài khoản không được đặt với quyền đọc ... Đang có nói rằng, hãy xem xét lại các cảnh báo:
sao chép tệp tĩnh ... CẢNH BÁO: Không sao chép được tệp trong html_static_file: c: \ users \ me \ appdata \ local \ Programs \ python \ python38 \ lib \ site-pack \ sphinx \ themes \ basic \ static / jquery-3.5 .1.js: PermissionError (13, 'Quyền bị từ chối')
CẢNH BÁO: Không sao chép được tệp trong html_static_file: c: \ users \ me \ appdata \ local \ Programs \ python \ python38 \ lib \ site-pack \ sphinx \ themes \ basic \ static / jquery.js: PermissionError (13, ' Quyền bị từ chối ')
Cũng có thể là trường hợp bạn đã xóa Sphinx khỏi cài đặt tài khoản của mình và các tệp / đường dẫn đơn giản là không có ở đó.
Tiếp theo, khi bạn cố gắng cài đặt lại Sphinx bằng cách sử dụng pipnó, không hoàn toàn rõ ràng nếu đó là sự cố bộ nhớ cache đã lỗi thời hoặc nếu pipđang tìm thấy Sphinx trong một cài đặt khác trên của bạn PYTHONPATH... Có thể là trường hợp Sphinx đã được cài đặt và thiết bị đầu cuối không đọc / quyền ghi (tùy thuộc vào tài khoản người dùng nào đã gọi thiết bị đầu cuối) hoặc thư mục có thể bị ẩn trong trình khám phá tệp ...
Tôi có thể làm gì để đặt lại hoàn toàn cài đặt Sphinx của mình và chạy lại tài liệu của mình?
Các cài đặt cơ sở Python của bạn (điểm 1 và 2 ở trên) chỉ được viết cho các thay đổi của hệ thống hoặc toàn bộ người dùng (không phải cho một thay đổi dự án cụ thể).
Chúng tôi khuyên bạn nên sử dụng a venv. (Nếu bạn chưa làm như vậy thì đây sẽ là thời điểm thích hợp để cân nhắc làm như vậy vì đây là giải pháp dễ dàng và sạch sẽ nhất). Điều này thoạt đầu có vẻ khó hiểu vì trong lịch sử đã có một số môi trường ảo cho Python . Hiện tại venvlà giải pháp được trích dẫn phổ biến nhất và sử dụng nó rất đơn giản, IDE của bạn phải có giao diện người dùng tích hợp để giúp bạn tạo nó với một vài cú nhấp chuột.
A venvlà một môi trường Python mở rộng cài đặt cơ sở của bạn, nó tránh phải thay đổi cài đặt cơ sở của bạn khi bạn phải thực hiện các thay đổi cụ thể của dự án (như cài đặt Sphinx, lý tưởng là venvkhông phải cài đặt cơ sở).
Cuối cùng, khi bạn chạy Sphinx từ thiết bị đầu cuối , bạn nên kích hoạt của bạnvenv trên thiết bị đầu cuối, nếu không, quá trình cài đặt Python được thực thi có thể phụ thuộc vào tài khoản người dùng đã gọi thiết bị đầu cuối.