0

My first public Python project is now on readthedocs (RTD). There is one problem I'm trying to fix, but without success so far.

I'm using the :async: option to mark coroutines. This is supported by sphinx 2.1+. RTD used sphinx 1.8.5 for my project. All coroutines are simply skipped from the HTML output, i.e not documented at all. That is quite bad.

I created docs/requirements.txt file in my project containing: sphinx>=2.1.0 and in RTD > admin > advanced settings I have entered: /docs/requirements.txt as "A pip requirements file needed to build your documentation. Path from the root of your project.". Don't know if this is the right way to specifiy the sphinx version. Anyway I tried.

The build failed:

ERROR: Could not open requirements file: [Errno 2] No such file or directory: '../../../../../../../../docs/requirements.txt'

How could I overcome these problems to have all coroutines properly documented?

VPfB
  • 14,927
  • 6
  • 41
  • 75
  • RTD cannot find your requirements file. Try specifying the path *relative* to the root of your project, not as absolute, by removing the leading slash. – Steve Piercy May 13 '20 at 12:49
  • @StevePiercy Yes, it helped. Thank you! My documentation finally looks like I it should. – VPfB May 13 '20 at 13:10

1 Answers1

1

RTD cannot find your requirements file. Try specifying the path relative to the root of your project, not as absolute, by removing the leading slash.

Steve Piercy
  • 13,693
  • 1
  • 44
  • 57
  • I still do not fully understand the underlying cause of the problem. _"Path from the root of your project."_ is the `PATH` portion of the final file location `/ROOT/PATH`, isn't it? Then if a relative path gives `/ROOT/PATH', an absolute should result in `/ROOT//PATH` whichh is equivalent. – VPfB May 14 '20 at 05:10
  • `/` is the root of the server, not the root of your project. All paths that start with `/` are absolute, not relative. `./` is the root of your project. It is relative to the working directory. You could specify the location of your requirements file either with a leading `./` or without. – Steve Piercy May 14 '20 at 09:40
  • Thanks for explaining. Somehow I did not expect that the path is used that way, because maybe it could allow file access outside of user's project. – VPfB May 14 '20 at 10:59
  • You can attempt to look there, and you could be denied permission to read it or write to it. The error message does not explicitly mention permissions, but that could be what is happening. – Steve Piercy May 14 '20 at 11:30