Skip to content

Commit 3413927

Browse files
nrichersnrichers
authored
Rework how we include notebooks in our docs site (#139)
* Rework Makefile, change to listing pages * Change git clone branch back to prod * Grid tweaks * Add fix for Quarto sidebar * Update notebook embeds, edits * Update notebook embeds, more edits * Edits, tweaks * Fix broken links * Address review comment * Tweak card preview, refresh notebook source, update rendered site * Modify Makefile to move Quickstart notebooks, re-render site, minor tweaks
1 parent 2fab61d commit 3413927

File tree

158 files changed

+50768
-12962
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

158 files changed

+50768
-12962
lines changed

‎site/Makefile

Lines changed: 14 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -30,40 +30,23 @@ clone:
3030
@echo "\nCloning source repos ..."
3131
git clone -b prod git@github.com:validmind/developer-framework.git $(SRC_DIR)
3232

33-
# Copy over Jupyter notebooks
34-
35-
NOTEBOOKS = \
36-
notebooks/quickstart_customer_churn_full_suite.ipynb \
37-
notebooks/external_test_providers_demo.ipynb \
38-
notebooks/external_tests/tests/MyCustomTest.py \
39-
notebooks/how_to/implementing_custom_tests.ipynb \
40-
notebooks/how_to/explore_test_suites_test_plans_and_tests.ipynb \
41-
notebooks/how_to/explore_test_suites_and_tests.ipynb \
42-
notebooks/how_to/run_a_test.ipynb \
43-
notebooks/how_to/run_a_test_suite.ipynb \
44-
notebooks/nlp/nlp_sentiment_analysis_catboost_demo.ipynb \
45-
notebooks/time_series/tutorial_time_series_forecasting.ipynb \
46-
notebooks/llm/hugging_face_integration_demo.ipynb \
47-
notebooks/probability_of_default/credit_risk_scorecard_development_demo.ipynb \
48-
notebooks/probability_of_default/credit_risk_scorecard_validation_demo.ipynb \
49-
notebooks/probability_of_default/helpers/scorecard_model.py \
50-
notebooks/probability_of_default/helpers/model_development.py \
51-
notebooks/llm/prompt_validation_demo.ipynb
52-
33+
# Copy over Jupyter notebooks and supporting files
5334
notebooks:
5435
@echo "\nUpdating notebook source ..."
55-
@rm -f notebooks.zip > /dev/null 2>&1
56-
@rm -rf $(DEST_DIR_NB)/ > /dev/null 2>&1 && mkdir -p $(DEST_DIR_NB)
57-
@$(foreach notebook,$(NOTEBOOKS), \
58-
dest_dir=$(DEST_DIR_NB)/$(patsubst notebooks/%,%,$(dir $(notebook))); \
59-
mkdir -p $$dest_dir > /dev/null 2>&1; \
60-
cp -r $(SRC_DIR)/$(notebook) $$dest_dir > /dev/null 2>&1; \
61-
echo "Updated $(notebook)"; \
62-
)
63-
@echo "\nCopying additional notebooks from Google Drive ..."
64-
cp "$(HOME)/Google Drive/Shared drives/ValidMind Demo/Notebooks/Introduction_Customer_Churn.ipynb" $(DEST_DIR_NB)/
65-
@echo "\nZipping up notebooks into notebooks.zip ..."
36+
@rm -f notebooks.zip
37+
@rm -rf $(DEST_DIR_NB)/ && mkdir -p $(DEST_DIR_NB)
38+
@cp -r $(SRC_DIR)/notebooks/. $(DEST_DIR_NB)/
39+
@echo "Copying LICENSE into notebooks ..."
40+
@cp -r $(SRC_DIR)/LICENSE $(DEST_DIR_NB)/
41+
@rm -rf $(DEST_DIR_NB)/code_sharing
42+
@echo "Moving Quickstart notebook into the root of notebooks/ ..."
43+
@if [ -f "$(DEST_DIR_NB)/code_samples/quickstart_customer_churn_full_suite.ipynb" ]; then mv $(DEST_DIR_NB)/code_samples/quickstart_customer_churn_full_suite.ipynb $(DEST_DIR_NB)/quickstart_customer_churn_full_suite.ipynb; fi
44+
@echo "Zip up notebooks.zip ..."
6645
@zip -r notebooks.zip $(DEST_DIR_NB) > /dev/null 2>&1
46+
# This line fixes text casing in Quarto when notebooks are embedded via wildcard
47+
@echo "Renaming code_samples/nlp_and_llm to fix Quarto sidebar ..."
48+
@if [ -d "$(DEST_DIR_NB)/code_samples/nlp_and_llm" ]; then mv $(DEST_DIR_NB)/code_samples/nlp_and_llm $(DEST_DIR_NB)/code_samples/LLM_and_NLP; fi
49+
6750

6851
# Make Python library docs & copy them over
6952
python-docs:

‎site/_quarto.yml

Lines changed: 14 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -28,27 +28,27 @@ website:
2828
menu:
2929
- text: "{{< fa rocket >}} Get Started"
3030
file: guide/get-started-developer-framework.qmd
31-
- text: "{{< fa cube >}} Supported Models"
31+
- text: "{{< fa cubes >}} Supported Models"
3232
file: guide/supported-models.qmd
3333
- text: "---"
3434
- text: "{{< fa code >}} CODE SAMPLES"
35-
- text: "{{< fa book >}} QuickStart · `Customer Churn` · `Binary Classification`"
35+
- text: "{{< fa book >}} Quickstart · `Customer Churn` · `Binary Classification`"
3636
file: notebooks/quickstart_customer_churn_full_suite.ipynb
37-
- text: "{{< fa book >}} Full Introduction · `Customer Churn` · `Binary Classification`"
38-
file: notebooks/Introduction_Customer_Churn.ipynb
39-
- text: "{{< fa book >}} Forecasting · `Credit Risk Scorecard` · `Time Series`"
40-
file: notebooks/time_series/tutorial_time_series_forecasting.ipynb
41-
- text: "{{< fa book >}} Natural Language Processing · `Sensitivity Analysis` · `Binary Classification`"
42-
file: notebooks/nlp/nlp_sentiment_analysis_catboost_demo.ipynb
43-
- text: "{{< fa code >}} Try it on Jupyter Hub!"
37+
# - text: "{{< fa book >}} Full Introduction · `Customer Churn` · `Binary Classification`"
38+
# file: notebooks/code_samples/Introduction_Customer_Churn.ipynb
39+
- text: "{{< fa book-open-reader >}} More Samples · `LLM` · `NLP` · `Time Series` · `Etc.`"
40+
file: guide/samples-jupyter-notebooks.qmd
41+
- text: "{{< fa download >}} Download Samples · `notebooks.zip`"
42+
file: notebooks.zip
43+
- text: "{{< fa hand-point-right >}} Try it on Jupyter Hub {{< fa hand-point-left >}}"
4444
file: https://jupyterhub.validmind.ai/
4545
- text: "---"
4646
- text: "{{< fa vial >}} TESTING"
47-
- text: "{{< fa vials >}} Run Tests & Test Suites"
47+
- text: "{{< fa flask-vial >}} Run Tests & Test Suites"
4848
file: guide/testing-overview.qmd
4949
- text: "---"
5050
- text: "{{< fa book >}} REFERENCE"
51-
- text: "Developer Framework {{< fa external-link >}}"
51+
- text: "{{< fa external-link >}} Developer Framework"
5252
file: validmind/validmind.html
5353
target: _blank
5454
- text: "FAQ"
@@ -179,27 +179,13 @@ website:
179179
- text: "---"
180180
# - guide/dataset-object.qmd
181181
# - guide/model-object.qmd
182-
- text: "Tests, test plans & test suites"
182+
- text: "Tests & test suites"
183183
file: guide/testing-overview.qmd
184-
contents:
185-
- notebooks/external_test_providers_demo.ipynb
186-
- notebooks/how_to/implementing_custom_tests.ipynb
187-
- notebooks/how_to/explore_test_suites_and_tests.ipynb
188-
- notebooks/how_to/run_a_test.ipynb
189-
- notebooks/how_to/run_a_test_suite.ipynb
184+
contents: "notebooks/how_to/*.ipynb"
190185
- text: "---"
191186
- text: "Code samples"
192187
file: guide/samples-jupyter-notebooks.qmd
193-
contents:
194-
- notebooks/quickstart_customer_churn_full_suite.ipynb
195-
- notebooks/Introduction_Customer_Churn.ipynb
196-
- notebooks/time_series/tutorial_time_series_forecasting.ipynb
197-
- text: "Sensitivity Analysis: Natural Language Processing Analysis & Binary Classification using CatBoost"
198-
file: notebooks/nlp/nlp_sentiment_analysis_catboost_demo.ipynb
199-
- text: "Credit Risk Scorecard Model Development"
200-
file: notebooks/probability_of_default/credit_risk_scorecard_development_demo.ipynb
201-
- text: "Credit Risk Scorecard Model Validation"
202-
file: notebooks/probability_of_default/credit_risk_scorecard_validation_demo.ipynb
188+
contents: "notebooks/code_samples/**"
203189
- text: "---"
204190
- test: "Reference"
205191
file: guide/reference.qmd

‎site/_site/guide/add-content-blocks.html

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -114,41 +114,37 @@
114114
</li>
115115
<li>
116116
<a class="dropdown-item" href="../guide/supported-models.html" rel="" target="">
117-
<span class="dropdown-text"><i class="fa-solid fa-cube" aria-label="cube"></i> Supported Models</span></a>
117+
<span class="dropdown-text"><i class="fa-solid fa-cubes" aria-label="cubes"></i> Supported Models</span></a>
118118
</li>
119119
<li><hr class="dropdown-divider"></li>
120120
<li class="dropdown-header"><i class="fa-solid fa-code" aria-label="code"></i> CODE SAMPLES</li>
121121
<li>
122122
<a class="dropdown-item" href="../notebooks/quickstart_customer_churn_full_suite.html" rel="" target="">
123-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> QuickStart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
123+
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Quickstart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
124124
</li>
125125
<li>
126-
<a class="dropdown-item" href="../notebooks/Introduction_Customer_Churn.html" rel="" target="">
127-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Full Introduction · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
126+
<a class="dropdown-item" href="../guide/samples-jupyter-notebooks.html" rel="" target="">
127+
<span class="dropdown-text"><i class="fa-solid fa-book-open-reader" aria-label="book-open-reader"></i> More Samples · <code>LLM</code> · <code>NLP</code> · <code>Time Series</code> · <code>Etc.</code></span></a>
128128
</li>
129129
<li>
130-
<a class="dropdown-item" href="../notebooks/time_series/tutorial_time_series_forecasting.html" rel="" target="">
131-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Forecasting · <code>Credit Risk Scorecard</code> · <code>Time Series</code></span></a>
132-
</li>
133-
<li>
134-
<a class="dropdown-item" href="../notebooks/nlp/nlp_sentiment_analysis_catboost_demo.html" rel="" target="">
135-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Natural Language Processing · <code>Sensitivity Analysis</code> · <code>Binary Classification</code></span></a>
130+
<a class="dropdown-item" href="../notebooks.zip" rel="" target="">
131+
<span class="dropdown-text"><i class="fa-solid fa-download" aria-label="download"></i> Download Samples · <code>notebooks.zip</code></span></a>
136132
</li>
137133
<li>
138134
<a class="dropdown-item" href="https://jupyterhub.validmind.ai/" rel="" target="">
139-
<span class="dropdown-text"><i class="fa-solid fa-code" aria-label="code"></i> Try it on Jupyter Hub!</span></a>
135+
<span class="dropdown-text"><i class="fa-solid fa-hand-point-right" aria-label="hand-point-right"></i> Try it on Jupyter Hub <i class="fa-solid fa-hand-point-left" aria-label="hand-point-left"></i></span></a>
140136
</li>
141137
<li><hr class="dropdown-divider"></li>
142138
<li class="dropdown-header"><i class="fa-solid fa-vial" aria-label="vial"></i> TESTING</li>
143139
<li>
144140
<a class="dropdown-item" href="../guide/testing-overview.html" rel="" target="">
145-
<span class="dropdown-text"><i class="fa-solid fa-vials" aria-label="vials"></i> Run Tests &amp; Test Suites</span></a>
141+
<span class="dropdown-text"><i class="fa-solid fa-flask-vial" aria-label="flask-vial"></i> Run Tests &amp; Test Suites</span></a>
146142
</li>
147143
<li><hr class="dropdown-divider"></li>
148144
<li class="dropdown-header"><i class="fa-solid fa-book" aria-label="book"></i> REFERENCE</li>
149145
<li>
150146
<a class="dropdown-item" href="../validmind/validmind.html" rel="" target="_blank">
151-
<span class="dropdown-text">Developer Framework <i class="fa-solid fa-external-link" aria-label="external-link"></i></span></a>
147+
<span class="dropdown-text"><i class="fa-solid fa-external-link" aria-label="external-link"></i> Developer Framework</span></a>
152148
</li>
153149
</ul>
154150
</li>

‎site/_site/guide/before-you-begin.html

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -112,41 +112,37 @@
112112
</li>
113113
<li>
114114
<a class="dropdown-item" href="../guide/supported-models.html" rel="" target="">
115-
<span class="dropdown-text"><i class="fa-solid fa-cube" aria-label="cube"></i> Supported Models</span></a>
115+
<span class="dropdown-text"><i class="fa-solid fa-cubes" aria-label="cubes"></i> Supported Models</span></a>
116116
</li>
117117
<li><hr class="dropdown-divider"></li>
118118
<li class="dropdown-header"><i class="fa-solid fa-code" aria-label="code"></i> CODE SAMPLES</li>
119119
<li>
120120
<a class="dropdown-item" href="../notebooks/quickstart_customer_churn_full_suite.html" rel="" target="">
121-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> QuickStart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
121+
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Quickstart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
122122
</li>
123123
<li>
124-
<a class="dropdown-item" href="../notebooks/Introduction_Customer_Churn.html" rel="" target="">
125-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Full Introduction · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
124+
<a class="dropdown-item" href="../guide/samples-jupyter-notebooks.html" rel="" target="">
125+
<span class="dropdown-text"><i class="fa-solid fa-book-open-reader" aria-label="book-open-reader"></i> More Samples · <code>LLM</code> · <code>NLP</code> · <code>Time Series</code> · <code>Etc.</code></span></a>
126126
</li>
127127
<li>
128-
<a class="dropdown-item" href="../notebooks/time_series/tutorial_time_series_forecasting.html" rel="" target="">
129-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Forecasting · <code>Credit Risk Scorecard</code> · <code>Time Series</code></span></a>
130-
</li>
131-
<li>
132-
<a class="dropdown-item" href="../notebooks/nlp/nlp_sentiment_analysis_catboost_demo.html" rel="" target="">
133-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Natural Language Processing · <code>Sensitivity Analysis</code> · <code>Binary Classification</code></span></a>
128+
<a class="dropdown-item" href="../notebooks.zip" rel="" target="">
129+
<span class="dropdown-text"><i class="fa-solid fa-download" aria-label="download"></i> Download Samples · <code>notebooks.zip</code></span></a>
134130
</li>
135131
<li>
136132
<a class="dropdown-item" href="https://jupyterhub.validmind.ai/" rel="" target="">
137-
<span class="dropdown-text"><i class="fa-solid fa-code" aria-label="code"></i> Try it on Jupyter Hub!</span></a>
133+
<span class="dropdown-text"><i class="fa-solid fa-hand-point-right" aria-label="hand-point-right"></i> Try it on Jupyter Hub <i class="fa-solid fa-hand-point-left" aria-label="hand-point-left"></i></span></a>
138134
</li>
139135
<li><hr class="dropdown-divider"></li>
140136
<li class="dropdown-header"><i class="fa-solid fa-vial" aria-label="vial"></i> TESTING</li>
141137
<li>
142138
<a class="dropdown-item" href="../guide/testing-overview.html" rel="" target="">
143-
<span class="dropdown-text"><i class="fa-solid fa-vials" aria-label="vials"></i> Run Tests &amp; Test Suites</span></a>
139+
<span class="dropdown-text"><i class="fa-solid fa-flask-vial" aria-label="flask-vial"></i> Run Tests &amp; Test Suites</span></a>
144140
</li>
145141
<li><hr class="dropdown-divider"></li>
146142
<li class="dropdown-header"><i class="fa-solid fa-book" aria-label="book"></i> REFERENCE</li>
147143
<li>
148144
<a class="dropdown-item" href="../validmind/validmind.html" rel="" target="_blank">
149-
<span class="dropdown-text">Developer Framework <i class="fa-solid fa-external-link" aria-label="external-link"></i></span></a>
145+
<span class="dropdown-text"><i class="fa-solid fa-external-link" aria-label="external-link"></i> Developer Framework</span></a>
150146
</li>
151147
</ul>
152148
</li>

‎site/_site/guide/collaborate-on-documentation-projects.html

Lines changed: 9 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -113,41 +113,37 @@
113113
</li>
114114
<li>
115115
<a class="dropdown-item" href="../guide/supported-models.html" rel="" target="">
116-
<span class="dropdown-text"><i class="fa-solid fa-cube" aria-label="cube"></i> Supported Models</span></a>
116+
<span class="dropdown-text"><i class="fa-solid fa-cubes" aria-label="cubes"></i> Supported Models</span></a>
117117
</li>
118118
<li><hr class="dropdown-divider"></li>
119119
<li class="dropdown-header"><i class="fa-solid fa-code" aria-label="code"></i> CODE SAMPLES</li>
120120
<li>
121121
<a class="dropdown-item" href="../notebooks/quickstart_customer_churn_full_suite.html" rel="" target="">
122-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> QuickStart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
122+
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Quickstart · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
123123
</li>
124124
<li>
125-
<a class="dropdown-item" href="../notebooks/Introduction_Customer_Churn.html" rel="" target="">
126-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Full Introduction · <code>Customer Churn</code> · <code>Binary Classification</code></span></a>
125+
<a class="dropdown-item" href="../guide/samples-jupyter-notebooks.html" rel="" target="">
126+
<span class="dropdown-text"><i class="fa-solid fa-book-open-reader" aria-label="book-open-reader"></i> More Samples · <code>LLM</code> · <code>NLP</code> · <code>Time Series</code> · <code>Etc.</code></span></a>
127127
</li>
128128
<li>
129-
<a class="dropdown-item" href="../notebooks/time_series/tutorial_time_series_forecasting.html" rel="" target="">
130-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Forecasting · <code>Credit Risk Scorecard</code> · <code>Time Series</code></span></a>
131-
</li>
132-
<li>
133-
<a class="dropdown-item" href="../notebooks/nlp/nlp_sentiment_analysis_catboost_demo.html" rel="" target="">
134-
<span class="dropdown-text"><i class="fa-solid fa-book" aria-label="book"></i> Natural Language Processing · <code>Sensitivity Analysis</code> · <code>Binary Classification</code></span></a>
129+
<a class="dropdown-item" href="../notebooks.zip" rel="" target="">
130+
<span class="dropdown-text"><i class="fa-solid fa-download" aria-label="download"></i> Download Samples · <code>notebooks.zip</code></span></a>
135131
</li>
136132
<li>
137133
<a class="dropdown-item" href="https://jupyterhub.validmind.ai/" rel="" target="">
138-
<span class="dropdown-text"><i class="fa-solid fa-code" aria-label="code"></i> Try it on Jupyter Hub!</span></a>
134+
<span class="dropdown-text"><i class="fa-solid fa-hand-point-right" aria-label="hand-point-right"></i> Try it on Jupyter Hub <i class="fa-solid fa-hand-point-left" aria-label="hand-point-left"></i></span></a>
139135
</li>
140136
<li><hr class="dropdown-divider"></li>
141137
<li class="dropdown-header"><i class="fa-solid fa-vial" aria-label="vial"></i> TESTING</li>
142138
<li>
143139
<a class="dropdown-item" href="../guide/testing-overview.html" rel="" target="">
144-
<span class="dropdown-text"><i class="fa-solid fa-vials" aria-label="vials"></i> Run Tests &amp; Test Suites</span></a>
140+
<span class="dropdown-text"><i class="fa-solid fa-flask-vial" aria-label="flask-vial"></i> Run Tests &amp; Test Suites</span></a>
145141
</li>
146142
<li><hr class="dropdown-divider"></li>
147143
<li class="dropdown-header"><i class="fa-solid fa-book" aria-label="book"></i> REFERENCE</li>
148144
<li>
149145
<a class="dropdown-item" href="../validmind/validmind.html" rel="" target="_blank">
150-
<span class="dropdown-text">Developer Framework <i class="fa-solid fa-external-link" aria-label="external-link"></i></span></a>
146+
<span class="dropdown-text"><i class="fa-solid fa-external-link" aria-label="external-link"></i> Developer Framework</span></a>
151147
</li>
152148
</ul>
153149
</li>

0 commit comments

Comments
 (0)