Relative paths in nested includes are inconsistent.

[nevetS]

Subject: Relative paths in nested includes are inconsistent.

Problem

• Relative paths in nested includes are inconsistent.

Procedure to reproduce the problem

make html

Create a project with the following directory structure:

├── project
│       └── config.txt
├── docs
│       ├── source
│       │       ├── index.rst
│       │       ├── configs
                       └── config.rst

WIthin index.rst:

.. include::  configs/config.rst

Within config.rst:

.. literalinclude: ../../../project/config.txt

.. literalinclude:  ../../project/config.txt

Error logs / results

WARNING: Include file u'/Users/myuser/project/config.txt' not found or reading it failed
WARNING: Include file u'/Users/myuser/src/project/docs/project/config.txt' not found or reading it failed

Expected results

File included in documentation.

It would be nice if absolute paths were possible for includes, but considering CI, fixing the relative path issue is the thing to do.

Reproducible project / your project

• Haven't put together a sample yet. Will update if necessary.

Environment info

• OS: OSX 10.11.6
• Python version: 2.7.13
• Sphinx version: 1.7.2

[tk0miya]

I reproduced the warnings with this Dockerfile:

FROM tk0miya/sphinx-html

RUN mkdir -p project docs/source/configs
RUN echo '' > project/config.txt
RUN echo '.. include::  configs/config.rst' > docs/source/index.rst
RUN echo 'master_doc = "index"' > docs/source/conf.py
RUN echo << EOF > docs/source/configs/config.rst \
.. literalinclude:: ../../../project/config.txt\\n\
\\n\
.. literalinclude::  ../../project/config.txt\\n
RUN cat docs/source/configs/config.rst
RUN sphinx-build docs/source _build/html

And this is console output:

Running Sphinx v1.7.1
making output directory...
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: 2 added, 0 changed, 0 removed
reading sources... [ 50%] configs/config
reading sources... [100%] index

/docs/docs/source/configs/config.rst:3: WARNING: Include file '/docs/docs/project/config.txt' not found or reading it failed
docs/source/configs/config.rst:1: WARNING: Include file '/project/config.txt' not found or reading it failed
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 50%] configs/config
writing output... [100%] index

generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 2 warnings.

The HTML pages are in _build/html.

/docs/docs/source/configs/config.rst:3: WARNING: Include file '/docs/docs/project/config.txt' not found or reading it failed

The first warning is emitted on parsing configs/config.rst itself. Sphinx considers it is one of document because of it has .rst extension.
If you don't want to process it, please rename it to other extensions like .txt and .includes.

docs/source/configs/config.rst:1: WARNING: Include file '/project/config.txt' not found or reading it failed

This one is emitted on parsing index.rst. The included contents are processed as a part of parent (includer) document. As a result, Sphinx searches the relative path ../../../project/config.txt based on index.rst, not configs/config.txt.

[tk0miya]

Sorry. I posted last comment on the way.

I think this is normal behavior of Sphinx.

It would be nice if absolute paths were possible for includes, but considering CI, fixing the relative path issue is the thing to do.

Both include and literalinclude directives supports absolute paths from "source directory". But project/config.txt is placed out of project directory in your case. So it is no way to do that.

[tk0miya]

This is not a bug of Sphinx. So I'm closing this.
Thanks,

Note: I improved the warning message on #4821. It will help you in next time :-)