การลบและติดตั้ง Python-Sphinx ใหม่บน Windows

Nov 15 2020

ฉันพยายามใช้ 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.

อย่างไรก็ตาม

ไฟล์ HTML kaesekuchenในbuildไม่ได้รับการปรับปรุง / เปลี่ยนแปลง
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinxไม่มีโฟลเดอร์นี้

ข้อหลังนี้เป็นความผิดของฉันเพราะฉันลบมันใน file explorer แต่เพียงเพราะฉันพบข้อผิดพลาดเดียวกันมาก่อนและหวังว่าการลบและติดตั้งใหม่Sphinxจะช่วยแก้ปัญหาได้

แต่คำสั่งpip uninstall sphinxและคำสั่งที่ตามมาpip install -U sphinxจะไม่เปลี่ยนแปลงอะไรในโฟลเดอร์นั้นและคำสั่งหลังจะให้เฉพาะเอาต์พุต upbeat ต่อไปนี้เท่านั้นแม้จะมีเอาต์พุตต่อไปนี้:

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 ใหม่ตั้งแต่เริ่มต้นโดยใช้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.

แต่ถึงแม้จะมีเอาต์พุตนี้ แต่ก็ไม่มีsourceการสร้างไฟล์หรือโฟลเดอร์ดังกล่าว

ฉันจะทำอย่างไรเพื่อรีเซ็ตการติดตั้ง Sphinx ใหม่ทั้งหมดและเรียกใช้เอกสารประกอบอีกครั้ง

คำตอบ

2 bad_coder Nov 16 2020 at 05:56

การแก้ปัญหานี้ต้องใช้คำอธิบายที่ค่อนข้างอึดอัดซึ่งขึ้นอยู่กับ: ระบบปฏิบัติการ (Windows) การติดตั้งเฉพาะของคุณและวิธีที่คุณใช้งาน Sphinx

บน Windows คุณสามารถติดตั้ง Python ได้หลายตัวในที่ต่างๆ (ขึ้นอยู่กับ ... ):

C:\Program Files\Python3xสถานที่ตั้งปกติหนึ่งคือ
เส้นทางเริ่มต้นที่กำหนดไว้ล่วงหน้าC:\Users\me\AppData\Local\Programs\Python\Python3.x\คือ ฉันพบว่ามันไม่สะดวกเพราะมันอยู่ลึกจากราก

วิธีขยายการติดตั้ง Python ที่แพร่หลายในปัจจุบันคือการใช้สภาพแวดล้อมเสมือน ( venv)

ของคุณvenvทุกที่ที่คุณตัดสินใจที่จะวางไว้ (การใช้ a venvถือเป็นแนวทางปฏิบัติที่ดีที่สุด"โดยพฤตินัย" )

ในช่วงเวลาหนึ่งคุณตั้งค่าPYTHONPATHเป็นตัวแปรสภาพแวดล้อมบน Windowsและอยู่ในเส้นทางเหล่านั้นที่ Windows จะค้นหาการติดตั้ง Python ของคุณ ขอให้สังเกตกฎสำหรับโมดูลเส้นทางการค้นหา ปัญหาตอนนี้กลายเป็นว่าหากคุณมีการติดตั้ง Python มากกว่าหนึ่งชุดบน Path ของคุณ Windows จะมองหาไลบรารีในการติดตั้งอื่น ๆ ...

(หมายเหตุทั่วไปเกี่ยวกับการติดตั้ง Python บน Windows เป็นสิ่งที่จำเป็นบางครั้งในปี 2019 Microsoft ได้รวม Python เข้ากับ Windows ตามที่ระบุไว้โดยผู้ใช้ SO ที่โดดเด่นในคำตอบนี้และอ้างถึงในเอกสารในช่วงเวลานั้นมีข้อบกพร่องของ Windows ที่ต้องใช้ตัวแปรสภาพแวดล้อม ที่จะตั้งค่าด้วยบัญชีผู้ดูแลระบบ - ฉันไม่พบข้อมูลอ้างอิง แต่มีการกล่าวถึงบางแห่งใน SO หมายความว่าขอแนะนำให้ทำการติดตั้ง Python แยกต่างหากและตั้งค่าตัวแปรสภาพแวดล้อมเป็นผู้ดูแลระบบ)

ต้องบอกว่าปัญหาที่คุณอธิบายมีหลายประการ (โปรดแจ้งให้ทราบเป็นพิเศษเกี่ยวกับเทอร์มินัลที่คุณใช้):

คำเตือนแรกในของคุณsphinx-buildบ่งชี้ว่า Sphinx กำลังพยายามอ่านไฟล์จากการติดตั้งบัญชีผู้ใช้ของคุณ (จุดที่ 2 ด้านบน) ปัญหาคือเทอร์มินัลที่คุณกำลังดำเนินการsphinx-buildไม่มีสิทธิ์ในการอ่านจากไดเร็กทอรีการติดตั้งบัญชีผู้ใช้เนื่องจากเทอร์มินัลกำลังทำงานภายใต้บัญชีผู้ใช้อื่นหรือเนื่องจากเส้นทางการติดตั้งบัญชีไม่ได้รับการตั้งค่าด้วยสิทธิ์ในการอ่าน ... กล่าวว่าพิจารณาคำเตือนใหม่:

คัดลอกไฟล์แบบคงที่ ... คำเตือน: ไม่สามารถคัดลอกไฟล์ใน 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, 'อนุญาตถูกปฏิเสธ')

คำเตือน: ไม่สามารถคัดลอกไฟล์ใน html_static_file: c: \ users \ me \ appdata \ local \ programs \ python \ python38 \ lib \ site-Packages \ sphinx \ themes \ basic \ static / jquery.js: PermissionError (13, ' ปฏิเสธการอนุญาต ')

อาจเป็นกรณีที่คุณลบ Sphinx ออกจากการติดตั้งบัญชีของคุณและไฟล์ / เส้นทางก็ไม่อยู่ที่นั่น

ถัดไปเมื่อคุณพยายามติดตั้ง Sphinx ใหม่โดยใช้pipจะไม่ชัดเจนว่าเป็นปัญหาแคชที่ล้าสมัยหรือหากpipพบ Sphinx ในการติดตั้งอื่นบนของคุณPYTHONPATH... อาจเป็นกรณีที่มีการติดตั้ง Sphinx และเทอร์มินัลไม่ได้อ่าน / เขียนอนุญาต (ขึ้นอยู่กับบัญชีผู้ใช้ที่เรียกใช้เทอร์มินัล) หรือไดเร็กทอรีอาจซ่อนอยู่ใน file explorer ...

ฉันจะทำอย่างไรเพื่อรีเซ็ตการติดตั้ง Sphinx ใหม่ทั้งหมดและเรียกใช้เอกสารประกอบอีกครั้ง

การติดตั้งฐาน Python ของคุณ (จุดที่ 1 และ 2 ด้านบน) ควรจะเขียนเพื่อการเปลี่ยนแปลงทั้งระบบหรือผู้ใช้เท่านั้น (ไม่ใช่สำหรับการเปลี่ยนแปลงโครงการใดโครงการหนึ่ง)

ขอแนะนำอย่างยิ่งให้คุณใช้ไฟล์venv. (หากคุณไม่เคยทำมาก่อนจะเป็นเวลาที่เหมาะสมในการพิจารณาทำเช่นนั้นเพราะเป็นวิธีที่ง่ายและสะอาดที่สุด) ในขั้นต้นนี้อาจดูเหมือนสับสนเพราะในอดีตมีหลายเสมือนสภาพแวดล้อมสำหรับงูหลาม ปัจจุบันvenvเป็นโซลูชันที่อ้างถึงมากที่สุดและการใช้งานนั้นง่าย IDE ของคุณควรมี UI ในตัวเพื่อช่วยให้คุณสร้างได้ด้วยการคลิกเพียงไม่กี่ครั้ง

A venvเป็นสภาพแวดล้อม Python ที่ขยายการติดตั้งฐานของคุณโดยหลีกเลี่ยงความจำเป็นในการเปลี่ยนการติดตั้งพื้นฐานของคุณเมื่อคุณต้องทำการเปลี่ยนแปลงเฉพาะโครงการ (เช่นการติดตั้ง Sphinx ควรอยู่ที่venvไม่ใช่การติดตั้งพื้นฐาน)

สุดท้ายเมื่อคุณเรียกใช้ Sphinx จากเทอร์มินัลขอแนะนำให้เปิดใช้งานvenvบนเทอร์มินัลมิฉะนั้นการติดตั้ง Python ที่ดำเนินการอาจขึ้นอยู่กับบัญชีผู้ใช้ที่เรียกใช้เทอร์มินัล