Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

locking documentation dependencies #51

Open
edublancas opened this issue Mar 31, 2023 · 2 comments
Open

locking documentation dependencies #51

edublancas opened this issue Mar 31, 2023 · 2 comments

Comments

@edublancas
Copy link
Contributor

edublancas commented Mar 31, 2023

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
Copy link
Contributor Author

edublancas commented Apr 13, 2023

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
Copy link
Contributor Author

edublancas commented Apr 13, 2023

To close this issue we need:

@edublancas edublancas added the good first issue Good for newcomers label Apr 13, 2023
@edublancas edublancas added stash Label used to categorize issues that will be worked on next high complexity and removed good first issue Good for newcomers labels May 23, 2023
@edublancas edublancas removed the stash Label used to categorize issues that will be worked on next label Jan 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant