Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Sphinx fails out when run at root directory inside of a container #10057

Closed
KengTeong opened this issue Jan 6, 2022 · 2 comments
Closed

Sphinx fails out when run at root directory inside of a container #10057

KengTeong opened this issue Jan 6, 2022 · 2 comments

Comments

@KengTeong
Copy link

KengTeong commented Jan 6, 2022

Bug Description

Attempting to local test container builds for sphinx documentation I ran across an issue where after completing QuickStart and attempting to run make html you get returned the following error. It appears that it fails to grab the intial p in /proc before attempting to navigate to cwd and due to this it does not find the file at all.

Example error:

Running Sphinx v4.3.2
/roc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
^C
Interrupted!
make: *** [Makefile:20: html] Interrupt

root@38d46495819d:/#

Example index.rst

.. dsa documentation master file, created by
   sphinx-quickstart on Thu Jan  6 18:42:52 2022.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to dsa's documentation!
===============================

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
root@38d46495819d:/# ```


### How to Reproduce

1. docker pull python:latest
2. podman run -it --entrypoint bash docker.io/python
3. pip3 install sphinx
4. sphinx-quickstart
5. fill in values recieve this output
```Creating file /conf.py.
Creating file /index.rst.
Creating file /Makefile.
Creating file /make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /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.
  1. run make html
root@38d46495819d:/# make html
Running Sphinx v4.3.2
making output directory... done
/roc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
/roc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/proc/1/cwd/index.rst: WARNING: document not readable. Ignored.
^C
Interrupted!
make: *** [Makefile:20: html] Interrupt

root@38d46495819d:/# 

Expected behavior

After running make html

[tester@test containers]$ make html
Running Sphinx v4.3.0
loading pickled environment... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 0 source files that are out of date
updating environment: 0 added, 0 changed, 0 removed
reading sources... [100%] index                                                                                                                                                                                                                                        
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] index                                                                                                                                                                                                                                         
generating indices... genindex done
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in _build/html.

Your project

N/A

Screenshots

image

image

OS

Debian GNU/Linux 11

Python versions

3.10.1, 3.9.2, 3.8.1

Sphinx version

4.3.2

Sphinx extensions

No response

Extra tools

No response

Additional context

I would like to note that it generally it is not a good idea to normally install to root. Whether that be a warn or a documentation change.

@tk0miya
Copy link
Member

tk0miya commented Jan 8, 2022

Indeed, the first characters of the paths are surely dropped when you put a Sphinx project onto the root directory. It must be a bug.

@tk0miya
Copy link
Member

tk0miya commented Jan 8, 2022

NOTE: I don't think it's nonsense to support the Sphinx project placed on the root directory. So I'll only fix the bug that Sphinx incorrectly drops the first character of each path on scanning documents. It will help users to exclude paths via exclude_patterns setting.

tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 8, 2022
get_matching_files() incorrectly drops the first character of each
path on scanning documents.  It will help users to exclude paths
via exclude_patterns setting.

Note: Users need to configure `exclude_patterns` to put their document
on the root directory.  This does not help to avoid recursive symlinks
(ex. /proc, /sys)
@tk0miya tk0miya added this to the 4.4.0 milestone Jan 8, 2022
tk0miya added a commit to tk0miya/sphinx that referenced this issue Jan 8, 2022
get_matching_files() incorrectly drops the first character of each
path on scanning documents.  It will help users to exclude paths
via exclude_patterns setting.

Note: Users need to configure `exclude_patterns` to put their document
on the root directory.  This does not help to avoid recursive symlinks
(ex. /proc, /sys)
tk0miya added a commit that referenced this issue Jan 11, 2022
Fix #10057: Failed to scan documents on the root directory
@github-actions github-actions bot locked as resolved and limited conversation to collaborators Feb 11, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

2 participants