Removendo e reinstalando Python-Sphinx no Windows
Estou tentando usar Python (3.8) e Sphinx (3.3.1) para construir uma documentação em HTML. No entanto, o sphinx-buildcomando me dá o seguinte erro:
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.
Contudo,
- O arquivo HTML
kaesekuchenembuildnão é atualizado / alterado. - A pasta
c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinxnão existe.
O último é minha culpa, porque eu o apaguei no explorador de arquivos, mas apenas porque eu encontrei exatamente o mesmo erro antes, e esperava que a exclusão e a reinstalação Sphinxresolvessem o problema.
Em vez disso, os comandos pip uninstall sphinxe os subsequentes pip install -U sphinxnão alteram nada nessa pasta, e o último fornece apenas a seguinte saída otimista, apesar da seguinte saída:
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
Mas a pasta c:\users\me\appdata\local\programs\python\python38\lib\site-packages\sphinx\ainda não está lá.
Eu até tentei executar um novo projeto Sphinx do zero, usando 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.
Mas, apesar dessa saída, esses arquivos ou sourcepastas não estão sendo criados.
O que posso fazer para redefinir de forma limpa a instalação do Sphinx e fazer com que minha documentação seja executada novamente?
Respostas
Resolver isso requer uma explicação um tanto estranha que depende simultaneamente de: sistema operacional (Windows), sua instalação particular e como você está executando o Sphinx.
No Windows, você pode ter várias instalações Python em locais diferentes (dependendo ...):
Um local comum é
C:\Program Files\Python3x.O caminho padrão pré-configurado é
C:\Users\me\AppData\Local\Programs\Python\Python3.x\. Acho isso inconveniente porque está localizado bem longe da raiz.
A maneira predominante de estender uma instalação Python é usando um ambiente virtual ( venv).
- Seu
venv, onde você decidiu colocá-lo. (Usar umvenvé considerado a prática recomendada "de fato" .)
Em um ponto no tempo, você define PYTHONPATHcomo uma variável de ambiente no Windows e é nesses caminhos que o Windows irá procurar por suas instalações Python. Observe as regras para o Caminho de pesquisa do módulo . O problema agora é que se você tiver mais de uma instalação do Python definida em seu caminho, o Windows também procurará bibliotecas em outras instalações ...
(Uma observação geral sobre as instalações do Python no Windows é necessária. Em algum momento de 2019, a Microsoft incluiu o Python com o Windows - conforme observado por um usuário proeminente do SO nesta resposta e referido na documentação . Naquela época, havia um bug do Windows que exigia variáveis de ambiente a ser definido com a conta do administrador - não consigo encontrar uma referência, mas é mencionado em algum lugar no SO. O que significa que é aconselhável fazer sua instalação separada do Python e definir as variáveis de ambiente como admin.)
Dito isso, o problema que você está descrevendo tem vários aspectos (preste atenção especial ao terminal que você está usando):
O primeiro aviso em seu sphinx-buildindica que o Sphinx está tentando ler arquivos da instalação da sua conta de usuário (ponto 2 acima). O problema é que o terminal onde você está executando sphinx-buildnão tem permissão para ler os diretórios de instalação da conta do usuário, porque o terminal está sendo executado com uma conta de usuário diferente ou porque os caminhos de instalação da conta não estão definidos com permissão de leitura ... Tendo disse isso, reconsidere os avisos:
copiando arquivos estáticos ... AVISO: Falha ao copiar um arquivo em 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, 'Permissão negada')
AVISO: Falha ao copiar um arquivo em html_static_file: c: \ users \ me \ appdata \ local \ programs \ python \ python38 \ lib \ site-packages \ sphinx \ themes \ basic \ static / jquery.js: PermissionError (13, ' Permissão negada')
Também pode ser o caso de você ter excluído o Sphinx da instalação da sua conta e os arquivos / caminhos simplesmente não estarem lá.
Em seguida, quando você tenta reinstalar o Sphinx usando pip, não está totalmente claro se é um problema de cache desatualizado ou se pipestá encontrando o Sphinx em outra instalação em seu PYTHONPATH... Pode ser o caso de Sphinx estar instalado e o terminal simplesmente não ler / permissão de gravação (depende de qual conta de usuário chamou o terminal), ou o diretório pode estar oculto no explorador de arquivos ...
O que posso fazer para redefinir de forma limpa a instalação do Sphinx e fazer com que minha documentação seja executada novamente?
Suas instalações de base do Python (pontos 1 e 2 acima) devem ser escritas apenas para mudanças no sistema ou no usuário (não para uma mudança de projeto em particular).
É altamente recomendável que você use a venv. (Se não o fez antes, este é o momento certo para pensar em fazer isso porque é a solução mais fácil e limpa). A princípio, isso pode parecer confuso porque, historicamente, houve vários ambientes virtuais para Python . Atualmente venvé a solução mais comumente citada e usá-la é simples, seu IDE deve ter uma IU embutida para ajudá-lo a criá-la com alguns cliques.
A venvé um ambiente Python que estende sua instalação básica, evita a necessidade de alterar sua instalação básica quando você tem que fazer alterações específicas do projeto (como instalar o Sphinx, idealmente deve ser na venvinstalação não básica).
Finalmente, quando você executa o Sphinx a partir do terminal , é aconselhável ativar o seuvenv no terminal, caso contrário, a instalação do Python executada pode depender da conta do usuário que invocou o terminal.