locking documentation dependencies

[edublancas]

Often our documentation breaks due to a change in a dependency; which causes all PRs to stall.

A better solution would be to pin all versions of the packages used and then install those versions:

# setup environment
pkgmt setup --doc

# generate a file with pinned version
conda env export --no-build --name ENV_NAME 

Note that we need to edit edit doc/environment.lock.yml and change the package (e.g., jupysql==0.7.0dev) for -e ...

Then, we update the .readthedocs.yml file to use such lock file.

Since it's essential to check that new package versions work, we can run this process in a cron job (e.g., every 2 weeks), so it re-generates the environment with the latest versions and opens a PR. If all goes well, we can merge it, otherwise, we can investigate and fix it without stalling PRs.

An important consideration is that conda env export does not generate cross-platform files, so we must ensure that we generate this file from a Linux machine, since that's what readthedocs uses.

example: ploomber/jupysql#345 (note that this hasn't been fully automated, I did everything manually)

[edublancas]

To generate the lock file from a non-linux machine:

docker run -i -t continuumio/miniconda3 /bin/bash

apt-get update
apt-get install build-essential

git clone https://github.com/ploomber/jupysql
cd jupysql

pip install pkgmt
pkgmt setup --doc

conda env export --no-build --name ENV_NAME > doc/environment.lock.yml

Not: this might still create issues if the architecture isn't the same. So we still have to check if github actions has the same architecture as readthedocs

[edublancas]

To close this issue we need:

• Open a PR to https://github.com/ploomber/pkgmt so running pkgmt setup --doc, executes conda env export --no-build and stores the output in doc/environment.lock.yml at the end
• Document this in the pkgmt documentation
• Open a PR and add a github actions sample workflow that re-generates the lock file every month and opens a PR https://github.com/ploomber/contributing/tree/main/sample-github-workflows. this can be useful since it already implements the logic to open a PR