From 7f7c4d1faab04a9a9e8a7fbc98dff91d97647648 Mon Sep 17 00:00:00 2001 From: vbarda Date: Thu, 12 Sep 2024 16:44:37 -0400 Subject: [PATCH 1/5] docs: add a README for updating notebooks/cassettes --- docs/README.md | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..25a81aa45 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,51 @@ +# Setup + +To setup requirements for building docs you can run: + +```bash +poetry install --with test +``` + +## Serving documentation locally + +To run the documentation server locally you can run: + +```bash +make serve-docs +``` + +## Execute notebooks + +If you would like to automatically execute all of the notebooks, to mimic the "Run notebooks" GHA, you can run: + +```bash +python docs/_scripts/prepare_notebooks_for_ci.py +./execute_notebooks.sh +``` + +**Note**: if you want to run the notebooks without `%pip install` cells, you can run: + +```bash +python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells +./execute_notebooks.sh +``` + +`prepare_notebooks_for_ci.py` script will add VCR cassette context manager for each cell in the notebook, so that: +* when the notebook is run for the first time, cells with network requests will be recorded to a VCR cassette file +* when the notebook is run subsequently, the cells with network requests will be replayed from the cassettes + +**Note**: this is currently limited only to the notebooks in `docs/docs/how-tos` + +## Adding new notebooks + +If you are adding a new notebook, please make sure to first run `prepare_notebooks_for_ci.py` script and + +```bash +jupyter execute +``` + +Once the notebook is executed, you should see the new VCR cassettes recorded in `docs/cassettes` directory. + +## Updating existing notebooks + +If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook and then run the steps from the "Adding new notebooks" section above. \ No newline at end of file From 8cf8e89b17d55614178fc1485dd3643bb7bb861e Mon Sep 17 00:00:00 2001 From: vbarda Date: Thu, 12 Sep 2024 16:45:40 -0400 Subject: [PATCH 2/5] clarification --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 25a81aa45..4d00048a0 100644 --- a/docs/README.md +++ b/docs/README.md @@ -48,4 +48,4 @@ Once the notebook is executed, you should see the new VCR cassettes recorded in ## Updating existing notebooks -If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook and then run the steps from the "Adding new notebooks" section above. \ No newline at end of file +If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `docs/cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above. \ No newline at end of file From a4149c9ffe951af9df4072118ad902bfdeeba375 Mon Sep 17 00:00:00 2001 From: vbarda Date: Thu, 12 Sep 2024 16:49:34 -0400 Subject: [PATCH 3/5] update and add script --- docs/README.md | 12 ++++++++---- docs/_scripts/execute_notebooks.sh | 5 +++++ 2 files changed, 13 insertions(+), 4 deletions(-) create mode 100755 docs/_scripts/execute_notebooks.sh diff --git a/docs/README.md b/docs/README.md index 4d00048a0..6f4e33ea7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,14 +20,14 @@ If you would like to automatically execute all of the notebooks, to mimic the "R ```bash python docs/_scripts/prepare_notebooks_for_ci.py -./execute_notebooks.sh +./docs/_scripts/execute_notebooks.sh ``` **Note**: if you want to run the notebooks without `%pip install` cells, you can run: ```bash python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells -./execute_notebooks.sh +./docs/_scripts/execute_notebooks.sh ``` `prepare_notebooks_for_ci.py` script will add VCR cassette context manager for each cell in the notebook, so that: @@ -38,13 +38,17 @@ python docs/_scripts/prepare_notebooks_for_ci.py --comment-install-cells ## Adding new notebooks -If you are adding a new notebook, please make sure to first run `prepare_notebooks_for_ci.py` script and +If you are adding a notebook with API requests, it's **recommended** to record network requests so that they can be subsequently replayed. If this is not done, the notebook runner will make API requests every time the notebook is run, which can be costly and slow. + +To record network requests, please make sure to first run `prepare_notebooks_for_ci.py` script. + +Then, run ```bash jupyter execute ``` -Once the notebook is executed, you should see the new VCR cassettes recorded in `docs/cassettes` directory. +Once the notebook is executed, you should see the new VCR cassettes recorded in `docs/cassettes` directory and discard the updated notebook. ## Updating existing notebooks diff --git a/docs/_scripts/execute_notebooks.sh b/docs/_scripts/execute_notebooks.sh new file mode 100755 index 000000000..6421e3a11 --- /dev/null +++ b/docs/_scripts/execute_notebooks.sh @@ -0,0 +1,5 @@ +for file in $(find docs/docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints") +do + echo "Executing $file" + jupyter execute "$file" +done \ No newline at end of file From 47831bcd9a89df8d72330542e43bcb659a453df6 Mon Sep 17 00:00:00 2001 From: vbarda Date: Fri, 13 Sep 2024 11:51:46 -0400 Subject: [PATCH 4/5] update script --- .github/workflows/run_notebooks.yml | 6 +----- docs/_scripts/execute_notebooks.sh | 2 +- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/.github/workflows/run_notebooks.yml b/.github/workflows/run_notebooks.yml index 32dafdbdd..de2d15131 100644 --- a/.github/workflows/run_notebooks.yml +++ b/.github/workflows/run_notebooks.yml @@ -49,11 +49,7 @@ jobs: TAVILY_API_KEY: ${{ secrets.TAVILY_API_KEY }} LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }} run: | - for file in $(find docs/docs/how-tos -name "*.ipynb") - do - echo "Executing $file" - PIP_PRE=1 poetry run jupyter execute "$file" - done + ./docs/_scripts/execute_notebooks.sh - name: Stop services run: make stop-services diff --git a/docs/_scripts/execute_notebooks.sh b/docs/_scripts/execute_notebooks.sh index 6421e3a11..0d1bb576f 100755 --- a/docs/_scripts/execute_notebooks.sh +++ b/docs/_scripts/execute_notebooks.sh @@ -1,5 +1,5 @@ for file in $(find docs/docs/how-tos -name "*.ipynb" | grep -v ".ipynb_checkpoints") do echo "Executing $file" - jupyter execute "$file" + poetry run jupyter execute "$file" done \ No newline at end of file From 70f6d2fb201f19f584d18297e938d98d6b3c0f71 Mon Sep 17 00:00:00 2001 From: vbarda Date: Fri, 13 Sep 2024 11:53:57 -0400 Subject: [PATCH 5/5] update --- docs/README.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 6f4e33ea7..df9d99882 100644 --- a/docs/README.md +++ b/docs/README.md @@ -52,4 +52,10 @@ Once the notebook is executed, you should see the new VCR cassettes recorded in ## Updating existing notebooks -If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `docs/cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above. \ No newline at end of file +If you are updating an existing notebook, please make sure to remove any existing cassettes for the notebook in `docs/cassettes` directory (each cassette is prefixed with the notebook name), and then run the steps from the "Adding new notebooks" section above. + +To delete cassettes for a notebook, you can run: + +```bash +rm docs/cassettes/* +``` \ No newline at end of file