FAQ is wrong?

[ruro]

Don't know if this is the correct place to report errors in the readthedocs documentation, but here goes.

The official documentation Frequently Asked Questions > Can I document a python package that is not at the root of my repository? page states (emphasis mine):

If you want to place your package in a different directory or have multiple python packages in the same project, then create a pip requirements file. You can specify the relative path to your package inside the file. For example you want to keep your python package in the src/python directory, then create a requirements.txt file with the following contents:

src/python/

Please note that the path must be relative to the file. So the example path above would work if the file is in the root of your repository. If you want to put the requirements in a file called requirements/requirements.txt, the contents would look like:

../python/

Unless I am misunderstanding something, this is wrong on 2 accounts.

1. The relative path would be ../src/python, not ../python.
2. Even with a "correct" relative path, this doesn't actually work, afaik, since pip install -r requirements/requirements.txt resolves the relative paths inside requirements.txt as if they were relative to the CWD, not to the requirements.txt file.

---

Piggybacking on this issue, I would like to ask if there is some way to control the CWD during the pip install -r step to make it so that the paths inside requirements.txt are actually resolved relative to its location?

I use pip-tools (pip-compile) to create my requirements.txt file and I would like to keep my requirements-related files in a subdirectory, however pip-tools version 7.0.0 will change relative path handling to be relative to the requirements.txt file, so doing a pip install -r requirements/requirements.txt from the root of the project will no longer work. Instead, I will have to cd requirements && pip install -r requirements.txt or pip-sync requirements/requirements.txt.

[stsewd]

The relative path would be ../src/python, not ../python.

Yes, that's right, the path is wrong.

since pip install -r requirements/requirements.txt resolves the relative paths inside requirements.txt as if they were relative to the CWD, not to the requirements.txt file.

Oh, if that's correct then we should change the recommendation to use https://docs.readthedocs.io/en/stable/config-file/v2.html#packages instead. But you won't be able to specify them in the requirements file.

And I don't think we would allow to change the cwd, but we are considering allowing to run arbitrary commands in some stages of the build, so things like this can be done (#6662).

[rajpratyush]

is this issue open for work?

[stsewd]

is this issue open for work?

yes!

[rajpratyush]

so i just have to change the FAQ documentation a\not the other part concerning with requirements.txt

[astrojuanlu]

since pip install -r requirements/requirements.txt resolves the relative paths inside requirements.txt as if they were relative to the CWD, not to the requirements.txt file.

I confirm this.

[astrojuanlu]

Related issue in pip-tools: jazzband/pip-tools#797 (closed as "won't fix")

[ruro]

however pip-tools version 7.0.0 will change relative path handling to be relative to the requirements.txt file

Related issue in pip-tools: jazzband/pip-tools#797 (closed as "won't fix")

I must have been very tired, when I wrote the last paragraph of the original post. I have confused 2 different pull requests in pip-tools. Somehow, I was under the impression that pull request jazzband/pip-tools#1329 was accepted and/or scheduled for the next milestone, this is not correct. That pull request indeed implements the "new" relative path handling that I was describing, but it's currently only a draft and not scheduled for any version/milestone AFAIK.

I think, I mixed it up with a different pull request that I was also following at the time that did get merged into the 6.1.0 release but is unrelated to the relative path handling issue. Sorry for any confusion.

[astrojuanlu]

No worries @ruro ! In any case, you were right about the FAQ and I submitted #8118 with a fix / clarification of that part, in case you want to have a look.

[ruro]

lgtm! :^)