needimport path is not consistent to other directives

[twodrops]

Other directives like image or include use relative path starting from rSt file. Looks like this is the standard.
needimport uses relative path starting from folder where conf.py is. This behavior is not consistent with the other directives.

Hint: Change to this behavior will break existing builds. Possibly it shall be changed asap or never.

[danwos]

Good point.
Absolute paths are starting from conf.py folder for e.g. image directive.
Relative paths from rst file.

I'm totally open to change this behavior for needimport to the sphinx default way.
Will do it already with the upcoming release.

[danwos]

This change will break the current implementation.

Maybe we can check if the "old" way is used to define the location (checking if file can be found) .
Then we throw an deprecation warning but go on without any error.

If old way does not lead to an existing file, use the new way (No warning).

[Chriner]

Wouldn't it be better to use the new way first?

• If file is found at new position, then OK.
• If not found at new position, then use old way
  • if file at old position found throw an deprecation warning and go on
  • if no file found throw error

[danwos]

@Chriner : You are right, that makes more sense.

For clarification:
conf.py under /home/me/project/docs.
Example rst under /home/me/project/docs/subfolder/page.rst

.. needimport:: /my.json   
    --> absolute from conf.py because of starting /
   --> /home/me/project/docs/my.json

.. needimport:: my.json  
   --> relative from current rst-file because of missing /
   --> /home/me/project/docs/subfolder/my.json

   * if not found, check /home/me/project/docs/my.json
     * if found there, use it but throw  DEPRECATION warning
     * if not found, raise already implemented exception/warning