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..?

[maurerle]

doc2path is deprecated in docutils as it throws Sphinx 9 will drop support for representing paths as strings. Use "pathlib.Path" or "os.fspath" instead. when used.
The core underlying issue I had here would be fixed with #73

As this issue has old wrong assumptions, I am closing it.