Cannot find relative path '../..' outside of root directory in Sphinx restructuredText: 'unknown document error'

Question

Even though I checked the relative path a million times (it is correct as measured from the document location wherein the reference is stated), still the error is thrown upon pushing the docs to AWS CodeBuild:

Warning, treated as error:
/codebuild/output/src192164467/src/docs/source/proj-repository-contents.rst:100:
unknown document: ../../src/lambda_functions/input/README.rst

The part where I reference the other .rst - document looks like so:

* input

    Supports the input ingestion pipelines.
    More details can be found in the :doc:`input Lambda functions <../../src/lambda_functions/input/README.rst>` - README.

How can I ensure that another document outside the active parent directory is found via e.g.

:doc:`some name <../../folder/filename.rst>`

?

---

EDIT: more approaches which did not work

As suggested here, one could include absolute paths into the conf.py - file like so:

SOURCE_PATH = os.path.join(LOCAL_PATH, '..', '..', 'src')
sys.path.insert(0, os.path.abspath(SOURCE_PATH))

Next, I tried to refer to one of the READMEs with the following approaches, which all failed due to the same 'unknown document error':

• <./lambda_functions/input/README.rst>
• </lambda_functions/input/README.rst>
• <lambda_functions/input/README.rst>

Just for curiosity, I tried with the general root directory of the project, but it also failed:

<src/lambda_functions/input/README.rst>

As a last resort, I tried it with a direct path to the folder where the README-file is located:

LAMBDA_INPUT_PATH = os.path.join(LOCAL_PATH, '..', '..', 'src',
                                 'lambda_functions', 'input')
sys.path.insert(0, os.path.abspath(LAMBDA_INPUT_PATH))

With this, I referred directly to the filename using <README.rst>, and even this failed.

Stinnett

Although for images, this answer also applies to documents. – Swear

Thanks, I tried out new approaches as detailed in the Edit. Yet, it seems to be impossible to refer to files above or outside the parent directory of the active via :doc:. In another document we have a working example using .. include:: ../../../src/packages/dist/ATTENTION.rst, maybe it depends on the type of referral (doc, include, figure, ...). – Stinnett

include is the only way I know to refer to a documentation file (not a module or extension) outside the documentation source directory. It's a common practice to include CHANGES.txt in the root of a project from the docs/changes.rst documentation file. Pyramid does this: raw.githubusercontent.com/Pylons/pyramid/master/docs/… Sphinx uses the configuration key root_doc to locate documentation source files relative to conf.py. Perhaps that is why sys.path.insert did not work? – Swear