Relative Path should use doc2path to be compatible with readthedocs style

[maurerle]

Summary

Builds have to be run from one specific directory, making it impossible to support both python -m sphinx -T -b html -d _build/doctrees -D language=en . $output from docs/source as well as make html from docs folder

Details

Currently, I am building my docs with something like this:

make -C docs html

This works with a directory structure like:

├── mypackage
│   ├── main.py
│   ├── cli.py
├── docs
│   ├── Makefile
│   ├── source
│   │   ├── conf.py
│   │   ├── index.rst
│   │   ├── cli.rst

and the cli.rst contains:

.. argparse::
   :filename: ../mypackage/cli.py
   :func: create_parser
   :prog: mypackage

This works fine, as the ../mypackage/cli.py path is relative to the docs dir which is used as a build dir by make.

The Problem

However, when running a readthedocs build, this does not work fine, as the build is created there using: cd docs/source python -m sphinx -T -b html -d _build/doctrees -D language=en . $OUTPUTDIR which starts the build from the source folder directly.

So we need to change :filename: ../mypackage/cli.py to :filename: ../../mypackage/cli.py to fix this.

Solution

I checked how nbsphinx-link is doing this - as this project does work in both ways: https://github.com/vidartf/nbsphinx-link/blob/f1682a8b5bfd884bfed7ef7dfaf0810c6ae8a543/nbsphinx_link/init.py I found that there is a doc2path api in sphinx which might correctly translate the pathes to be relative to the calling file in both ways: https://www.sphinx-doc.org/en/master/extdev/envapi.html

This would probably have the drawback, that sphinx-argparse should move to a "argparse is relative to the .rst file - not to the build dir of the docs" approach which would break existing configs..?