Readthedocs.org: support setup.cfg packages

[nschloe]

I recently switched some of my packages (e.g., https://github.com/nschloe/meshplex) from setup.py to setup.cfg + pyproject.toml. Since then, the doc builds are failing:

https://readthedocs.org/projects/meshplex/builds/10929512/

/home/docs/checkouts/readthedocs.org/user_builds/meshplex/envs/stable/bin/python: can't open file '/home/docs/checkouts/readthedocs.org/user_builds/meshplex/checkouts/stable/setup.py': [Errno 2] No such file or directory

[paternal]

This might be a problem on your side: the setuptools documentation reads:

Important: A setup.py file containing a setup() function call is still required even if your configuration resides in setup.cfg.

And Brett Cannon (a Python core developer) gives the minimum setup.py file:
~~~python

!/usr/bin/env python

import setuptools

if __name__ == "__main__":
setuptools.setup()
~~~

-- Louis

[stsewd]

As @nschloe mentions, you still need a setup.py file.

[pganssle]

@paternal @stsewd That is inaccurate, you do not need a setup.py file if you have a pyproject.toml file. In the very same article you link to Brett says:

But there's a bonus if you use a pyproject.toml file with a setup.cfg configuration for setuptools: you don't need a setup.py file anymore! Since tools like pip are going to call setuptools using the PEP 517 API instead of setup.py it means you can delete that setup.py file

It is also true that we're trying to deprecate setup.py install in setuptools, and setup.py install has been unsupported for several years (which is to say, if you find a bug when using setup.py install that can be fixed by using pip install, we don't usually fix that bug). RTD should use pip install instead of setup.py install 100%.

[stsewd]

@nschloe @pganssle you can already use pip to install your packages inside Read the Docs, please check https://docs.readthedocs.io/en/stable/config-file/v2.html#packages

[pganssle]

@stsewd It's not a great defaut to use setup.py install, though. It will likely start breaking when we remove setup.py install at some point in the future. It would be a good idea to start making the transition to installing with pip install by default.

[stsewd]

@pganssle when using a configuration file (v2) we don't install the package by default, we are moving away from executing things implicitly. Same when using the web interface.

[pganssle]

@stsewd The web interface only has an option for "Install with setup.py install". I think you should either remove that or have it use pip install.

[stsewd]

@pganssle we recommend using a configuration file, the web interface has a note about that.

[pganssle]

OK. If it breaks for you it breaks, I suppose.

I would recommend that in the future you not give inaccurate responses like "you still need a setup.py file."

[stsewd]

I would recommend that in the future you not give inaccurate responses like "you still need a setup.py file."

Yeah, sorry. I didn't know when using a pyproject file it wasn't needed.

[nschloe]

Using the config file, I'm getting the build error

ModuleNotFoundError: No module named 'importlib_metadata'

https://readthedocs.org/projects/meshplex/builds/10993781/

It seems that, indeed, readthedocs does install the package, and further that I have to specify the dependencies elsewhere. This is less than ideal. :frowning_face:

[stsewd]

@nschloe when using a config file, the settings from the UI are ignored, you can specify multiple installation methods (pip + requirements file), or just pip, the same way you'll install your package locally.

[nschloe]

I gather from here that the default is pip, but from the logs, it doesn't seem to get used at all (except for installing sphinx etc.).

[stsewd]

@nschloe that's the default value if you use something like

python:
  install:
    - path: .

That being the same as

python:
  install:
    - path: .
      method: pip

[nschloe]

I don't understand. It's not the default if you have to specify it, right? The docs say

Default: pip

but my logs don't have pip install . anywhere.

[stsewd]

@nschloe is the default if you use the python.install.path key, otherwise we don't install anything.

[nschloe]

Got it: _If_ the package is installed (which isn't the default), it used pip by default. Thanks!