Add support for toctree directive to include "backwards" path

[PedroAlfNeto]

If toctree supported backwards pathing, not forcing a top down project, would allow for better document reusability.
Please note the example bellow:

Example project

Directory structure:

  . 
  ├── common
  │   ├── copyright_front.rst
  │   └── cp_image.png
  │
  ├── proj
  │     ├──doc_proj
  │    ... ├── index.rst
  │        └── conf.py
 ...

Document index: proj/doc_proj/index.rst

..  toctree::
    :caption: Contents

   ../../common/copyright_front.rst

Common copyright front page shared by many documents: common/copyright_front.rst

... with the copyright symbol
    .. include:: ./ cp_image.png

I know the include directive supports this but it will break subsequent paths defined in called document (e.g. copyright_front)

[picnixz]

My 2 cents:

AFAICT, Sphinx is built assuming a top-down project structure, so if we were to allow "out of the box" documents that are not inside the project per se, I think wew need to do it properly for all include-like directives.

A more general approach would require the following:

• you should be able to include a document from wherever it is on the filesystem
• if the included document also includes other documents, then relative paths should be first resolved according to the original location of the included document. This means that we need to store a mapping of the included documents and their internal included paths.
• all include-like directives should support this feature and should work without breaking internal paths. This includes the .. figure or the .. literalinclude directives.
• This new behaviour may break a lot of existing projects, so the best is to have a switch for that (i.e., switch between a top-down project to a "normally structured" project where you can include whatever from wherever you want).

I am personally in support of this because it could reduce a lot the things you do. However, I would understand that this breaks the "independency" of a project. If you want to publish your project, you somewhat need to also ship the files "outside" of the project so that users could also generate the documentation on their own. For a local project, it's fine because it's your own FS, but for a public project, it might not be the best idea.

A solution would be to create some "vendor" directory in which you put symlinks to your shared files. Then you could upload the real file (instead of the symlink) when sharing the project. Still, you somewhat need to fix the included paths.

[electric-coder]

@AA-Turner this issue is an exact duplicate of the much older #701 where relative paths below the root are also extensively mentioned. The duplicate issue also includes a link to the canonical Stack Overflow post Can sphinx link to documents that are not located in directories below the root document? where plenty of workarounds are demonstrated.