2

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.

Andreas L.
  • 3,239
  • 5
  • 26
  • 65
  • Although for images, [this answer also applies to documents](https://stackoverflow.com/a/43714722/2214933). – Steve Piercy Oct 19 '21 at 08:30
  • 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, ...). – Andreas L. Oct 19 '21 at 09:55
  • `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: https://raw.githubusercontent.com/Pylons/pyramid/master/docs/changes.rst Sphinx uses the configuration key [`root_doc`](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-root_doc) to locate documentation source files relative to `conf.py`. Perhaps that is why `sys.path.insert` did not work? – Steve Piercy Oct 20 '21 at 03:10

0 Answers0