DOV-Vlaanderen/pydov

Update documentation on requirements files.

Roel opened this issue · 6 comments

Roel commented

The current documentation on our different requirements files (..) is not entirely up-to-date.

We should

  • remove the requirements_appveyor.txt as this was removed in #251
  • add docs/requirements_rtd.txt which is not mentioned now

I wonder if we cannot reuse the same requirements file for both Binder and Read The Docs (and requirements_docs.txt?) 😕

stijnvanhoey commented

See #294 for the adjustment (update on current setup). I do agree the current set of files is rather annoying, but a bit linked to our setup (having dependencies for our tutorials only, using binder and readthedocs each with specific configurations).

What we could do is merge dev and doc requirements. We split these for different 'contributor profiles', but in practice this is probably not very useful?

Roel commented

I don't really mind the dev and doc requirements being split. What did (does) confuse me is why we have three different documentation requirements files:

  • requirements_doc.txt
  • docs/requirements_rtd.txt
  • binder/requirements.txt

After all, their purpose is the same? I.e. install all dependencies required to run the notebooks, these are the same when running locally, on ReadTheDocs and on Binder?

I wonder whether we cannot consolidate them into one requirements file and use this both in RtD and Binder (and locally?). F.ex. in readthedocs.yml we can specify which requirements file to use.

stijnvanhoey commented

I do think we can get rid of the docs/requirements_rtd.txt by adjusting the readthedocs yaml file settings (see docs):

python:
  version: 3.7
  install:
    - requirements: requirements.txt 
    - requirements: requirements_dev.txt
    - requirements: requirements_doc.txt

instead of


requirements_file: docs/requirements_rtd.txt

python:
    version: 3
    setup_py_install: true

With respect to the Binder-configuration, I'm not aware of an option to combine multiple requirement files (requirement.txt and requirements_doc.txt) to setup the configuration (cfr. the underlying repo2docker documentation). Would be great if the option would exist. If not, we could work with a single requirement.txt in the main folder with all tutorial dependencies included file, but I would not do that.

stijnvanhoey commented

Checking the dev requirments as well, I do think we would need to check the behavior of

https://github.com/DOV-Vlaanderen/pydov/blob/master/requirements_dev.txt#L1

within the readthedocs context.

Roel commented

Can we use something like this with the extra_requirements? We specify docs in https://github.com/DOV-Vlaanderen/pydov/blob/master/setup.py#L57 ?

repo2docker supports setup.py installation too, although it appears to be lower in priority than the requirements.txt itself..

Roel commented

I removed the requirements_rtd.txt while I was at it fixing the readthedocs config. Documentation now builds with Python3.9 and pandas 1.4.0, and seems to work again :)

  • 👍1