Skip to content

Commit 791fcf5

Browse files
committed
Completed updating/creating remaning docs, documentation restructuring and content consolidation.
## 🏗️ Navigation & Structure - Reorganized myst.yml with intuitive folder structure (Authoring, Publishing, Command Line Tools, Computational, Site Design, Reference, Getting Started) - Removed 'Quick Start' and 'Curvenote Editor' sections from TOC - Moved files to logical locations and updated all cross-references ## �� New Documentation - Created comprehensive integrations/github.md reference guide - Added Getting Started section with 3 new guides: * account-setup.md - Account creation and profile management * first-steps-after-installation.md - Post-installation setup * basic-content-creation.md - Content creation fundamentals - Created authoring/myst-markdown.md with MyST syntax guide - Added authoring/adding-content.md for content management ## 🔄 File Reorganization - Moved GitHub-related files to publishing/ (github-actions.md, deploying-myst-from-github.md, submissions-using-github.md) - Moved computational files to Computational/ directory - Moved export files to publishing/ (export-latex.md, export-pdf.md) - Moved interactive files to Computational/ (interactive-outputs-in-jupyter.md, reproducible-figures.md) - Renamed authoring/authors.md to authoring/manage-authors.md ## ✨ Content Improvements - Updated all new files to use consistent 'Overview' section headers - Made computational guides more cohesive by combining tips and important notes - Fixed rendering issues in myst-markdown.md and adding-content.md - Updated all cross-references to point to new file locations - Ensured content accuracy by removing 'invented' features ## 🧹 Cleanup - Removed duplicate update-content.md file - Deleted old quick-start/ directory files - Consolidated scattered GitHub documentation into unified reference - Fixed broken links throughout documentation ## 📋 Documentation Standards - Applied consistent structure (Overview, Before You Start, numbered sections, Next Steps) - Used :::{important} syntax for callouts - Ensured all content reflects existing Curvenote features only"
1 parent 35c2bb8 commit 791fcf5

36 files changed

+6562
-885
lines changed

Computational/about-computational-articles.md

Lines changed: 531 additions & 0 deletions
Large diffs are not rendered by default.

Computational/computational-best-practices.md

Lines changed: 493 additions & 0 deletions
Large diffs are not rendered by default.

Computational/computational-tiers.md

Lines changed: 701 additions & 0 deletions
Large diffs are not rendered by default.

Computational/embed-notebooks.md

Lines changed: 391 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,391 @@
1+
---
2+
title: Embed Notebooks in Computational Content
3+
short_title: Embed Notebooks
4+
---
5+
6+
# Embed Notebooks in Computational Content
7+
8+
## Overview
9+
Integrate Jupyter notebooks into your Curvenote articles and reports to create rich, interactive computational content
10+
11+
Embedding notebooks allows you to combine narrative text with executable code, interactive visualizations, and computational outputs. Curvenote provides seamless integration between Jupyter notebooks and articles, enabling you to create computational articles and reports that maintain the full power of Jupyter while providing a structured, publication-ready format.
12+
13+
## Before You Start
14+
15+
Make sure you have:
16+
- A Curvenote project with computational content
17+
- Jupyter notebooks (`.ipynb` files) ready to embed
18+
- Understanding of notebook cell types and structure
19+
- Access to the Curvenote editor interface
20+
- Knowledge of MyST Markdown syntax
21+
22+
## 1. Understand Notebook Integration
23+
24+
Learn how notebooks work with Curvenote:
25+
26+
### Notebook Cell Types
27+
Curvenote recognizes three types of Jupyter notebook cells:
28+
29+
**Code Cells**:
30+
- Contain executable code (Python, R, Julia, etc.)
31+
- Can only be edited and run in Jupyter
32+
- Display as read-only in Curvenote articles
33+
- Produce output cells when executed
34+
35+
**Output Cells**:
36+
- Contain results from code execution
37+
- Can include text, images, tables, or interactive plots
38+
- Automatically linked to their code cells
39+
- Can be imported as figures in articles
40+
41+
**Markdown Cells**:
42+
- Contain rich text and documentation
43+
- Can be edited in both Jupyter and Curvenote
44+
- Support MyST Markdown syntax
45+
- Integrate seamlessly with article content
46+
47+
### Integration Workflow
48+
```mermaid
49+
graph LR
50+
A[Jupyter Notebook] --> B[Upload to Curvenote]
51+
B --> C[Edit in Curvenote]
52+
C --> D[Import Cells to Articles]
53+
D --> E[Publish Computational Content]
54+
```
55+
56+
## 2. Upload and Link Notebooks
57+
58+
Add your Jupyter notebooks to Curvenote:
59+
60+
### Upload Pre-Executed Notebooks
61+
```{important}
62+
Always upload pre-executed notebooks to Curvenote so that outputs are visible and available for use.
63+
```
64+
65+
**Step 1: Prepare Your Notebook**
66+
1. **Execute all cells** in Jupyter Lab or Jupyter Notebook
67+
2. **Save the notebook** with outputs included
68+
3. **Verify all outputs** are displayed correctly
69+
70+
**Step 2: Upload to Curvenote**
71+
1. **Navigate to your project** in Curvenote
72+
2. **Click the Upload icon** (☁️⬆️) in the project panel
73+
3. **Drag and drop** your `.ipynb` file or click to browse
74+
4. **Click "DONE"** to complete the upload
75+
76+
```{figure} images/m59m7JQmWVyPjlASj9v3-UGpUYCC2QlQIhNSTYmEh-v1.mp4
77+
:name: upload-notebook
78+
:align: center
79+
:width: 100%
80+
```
81+
82+
### Link Local Notebooks
83+
For notebooks you want to continue editing:
84+
85+
**Step 1: Link Existing Notebook**
86+
1. **Copy the OXA link** from your Curvenote notebook
87+
2. **Open your local Jupyter environment**
88+
3. **Use the link** to establish the connection
89+
90+
**Step 2: Sync Changes**
91+
```bash
92+
# In your local Jupyter environment
93+
# Make changes to your notebook
94+
# Save the notebook
95+
# Changes will sync to Curvenote
96+
```
97+
98+
## 3. Import Notebook Cells
99+
100+
Bring notebook content into your articles:
101+
102+
### Import Output Cells as Figures
103+
```{tip}
104+
Output cells from notebooks can be imported as figures in your articles, maintaining their interactive properties.
105+
```
106+
107+
**Step 1: Copy Cell Link**
108+
1. **Open your notebook** in Curvenote
109+
2. **Select the output cell** you want to import
110+
3. **Click the ⋮ Options menu** in the upper right
111+
4. **Select "Copy Link"**
112+
113+
**Step 2: Import into Article**
114+
1. **Open your article** in Draft Mode
115+
2. **Select the location** where you want the cell
116+
3. **Paste the link** and press Enter
117+
4. **The cell appears** as a block in your article
118+
119+
### Import Code Cells
120+
```python
121+
# Code cells can be imported for reference
122+
# They will display as read-only code blocks
123+
import pandas as pd
124+
import matplotlib.pyplot as plt
125+
126+
# Your computational code here
127+
data = pd.read_csv('experiment_data.csv')
128+
plt.plot(data['x'], data['y'])
129+
plt.show()
130+
```
131+
132+
### Import Markdown Cells
133+
```{myst}
134+
# Markdown cells integrate seamlessly with articles
135+
# They can be edited in both Jupyter and Curvenote
136+
137+
## Analysis Results
138+
139+
Our computational analysis revealed significant patterns in the data.
140+
The results are shown in the interactive plot below.
141+
```
142+
143+
## 4. Create Interactive Visualizations
144+
145+
Embed interactive plots and outputs:
146+
147+
### Supported Interactive Libraries
148+
Curvenote supports interactive outputs from these libraries:
149+
150+
**Python Libraries**:
151+
- **Plotly**: Interactive plots with zoom, pan, hover
152+
- **Altair**: Declarative statistical visualizations
153+
- **Bokeh**: Interactive web plots and dashboards
154+
- **Matplotlib**: Static plots with publication quality
155+
- **Seaborn**: Statistical data visualization
156+
- **Pandas**: Interactive data tables
157+
158+
**R Libraries**:
159+
- **Plotly**: Interactive R plots
160+
- **ggplot2**: Static statistical plots
161+
- **DT**: Interactive data tables
162+
- **Leaflet**: Interactive maps
163+
164+
### Create Interactive Plots
165+
```python
166+
# Example: Create interactive Plotly plot
167+
import plotly.express as px
168+
import pandas as pd
169+
170+
# Load data
171+
data = pd.read_csv('experiment_results.csv')
172+
173+
# Create interactive scatter plot
174+
fig = px.scatter(data, x='x_value', y='y_value',
175+
color='category', size='magnitude',
176+
hover_data=['condition', 'time'],
177+
title='Interactive Experimental Results')
178+
179+
fig.show()
180+
```
181+
182+
### Embed in Articles
183+
```{myst}
184+
## Results
185+
186+
Our analysis produced the following interactive visualization:
187+
188+
[Interactive plot will appear here when imported from notebook]
189+
190+
The plot shows significant differences between experimental conditions.
191+
```
192+
193+
## 5. Structure Computational Articles
194+
195+
Organize your content effectively:
196+
197+
### Article Structure with Embedded Notebooks
198+
```{myst}
199+
# Computational Article Title
200+
201+
## Abstract
202+
203+
Brief summary of your computational research.
204+
205+
## Introduction
206+
207+
Background and research objectives.
208+
209+
## Methods
210+
211+
### Data Processing
212+
[Import code cell showing data loading and preprocessing]
213+
214+
### Analysis Pipeline
215+
[Import code cell showing analysis steps]
216+
217+
## Results
218+
219+
### Interactive Visualizations
220+
[Import output cell with interactive plot]
221+
222+
### Statistical Analysis
223+
[Import output cell with statistical results]
224+
225+
## Discussion
226+
227+
Interpretation of results and implications.
228+
229+
## Code Availability
230+
231+
The complete analysis is available in the embedded notebook.
232+
```
233+
234+
### Mixed Content Approach
235+
```{myst}
236+
## Data Analysis
237+
238+
We analyzed the experimental dataset using Python's pandas library.
239+
240+
```{code-cell} python
241+
# Import and process data
242+
import pandas as pd
243+
import numpy as np
244+
245+
data = pd.read_csv('experiment_data.csv')
246+
print(f"Dataset shape: {data.shape}")
247+
print(f"Columns: {list(data.columns)}")
248+
```
249+
250+
The analysis revealed three key findings:
251+
252+
1. **Finding 1**: Description of the first result
253+
2. **Finding 2**: Description of the second result
254+
3. **Finding 3**: Description of the third result
255+
256+
[Interactive visualization imported from notebook output cell]
257+
```
258+
259+
## 6. Version Control and Collaboration
260+
261+
Manage notebook versions and collaborate effectively:
262+
263+
### Version Control
264+
```{important}
265+
Each notebook cell is versioned individually in Curvenote, allowing for precise tracking of changes.
266+
```
267+
268+
**Cell Versioning**:
269+
- **Individual cell versions**: Track changes to specific cells
270+
- **Notebook versions**: Save complete notebook states
271+
- **Cross-references**: Link to specific cell versions
272+
273+
**Version Management**:
274+
1. **Save cell versions** as you develop
275+
2. **Track changes** through version history
276+
3. **Revert to previous versions** if needed
277+
4. **Compare versions** to see differences
278+
279+
### Collaboration Features
280+
```{myst}
281+
## Collaborative Workflow
282+
283+
1. **Share notebooks** with collaborators
284+
2. **Edit markdown cells** in Curvenote
285+
3. **Edit code cells** in Jupyter
286+
4. **Sync changes** automatically
287+
5. **Review and approve** versions
288+
```
289+
290+
## 7. Configure Computational Environment
291+
292+
Set up your project for notebook integration:
293+
294+
### Project Configuration
295+
```yaml
296+
# curvenote.yml
297+
version: 1
298+
project:
299+
title: "My Computational Article"
300+
description: "Research with embedded Jupyter notebooks"
301+
302+
# Enable Jupyter features
303+
jupyter: true
304+
305+
# Export formats
306+
exports:
307+
- format: meca
308+
- format: pdf
309+
- format: typst
310+
311+
# Dependencies
312+
requirements:
313+
- requirements.txt
314+
- environment.yml
315+
316+
# Resources
317+
resources:
318+
- notebooks/*.ipynb
319+
- data/processed/*
320+
- src/**/*
321+
322+
# Computational settings
323+
computational:
324+
binderhub: true
325+
jupyter: true
326+
```
327+
328+
### Environment Dependencies
329+
```txt
330+
# requirements.txt
331+
pandas>=1.5.0
332+
numpy>=1.21.0
333+
matplotlib>=3.5.0
334+
seaborn>=0.11.0
335+
plotly>=5.0.0
336+
altair>=4.2.0
337+
jupyterlab>=3.5.0
338+
jupyterlab-myst>=0.2.0
339+
```
340+
341+
## 8. Best Practices
342+
343+
Follow these guidelines for effective notebook embedding:
344+
345+
### Notebook Preparation
346+
- **Execute all cells** before uploading
347+
- **Clear outputs** if notebooks are large
348+
- **Use descriptive cell names** for easy identification
349+
- **Include comprehensive documentation** in markdown cells
350+
351+
### Content Organization
352+
- **Structure notebooks logically** with clear sections
353+
- **Separate concerns** between different notebooks
354+
- **Use consistent naming conventions**
355+
- **Include setup and installation instructions**
356+
357+
### Performance Optimization
358+
- **Limit notebook size** for faster loading
359+
- **Use efficient data structures** and algorithms
360+
- **Cache expensive computations** when possible
361+
- **Optimize interactive plots** for web display
362+
363+
### Collaboration Guidelines
364+
- **Document your workflow** clearly
365+
- **Use version control** for all changes
366+
- **Communicate changes** to collaborators
367+
- **Test notebooks** in different environments
368+
369+
### Publication Readiness
370+
- **Ensure reproducibility** with proper dependencies
371+
- **Include data sources** and citations
372+
- **Provide clear instructions** for reproduction
373+
- **Test the complete workflow** before publishing
374+
375+
## Next Steps
376+
377+
- [Learn about Computational Best Practices →](./best-practices.md)
378+
- [Create Computational Articles →](../computational-articles.md)
379+
- [Understand Live Compute →](../live-compute.md)
380+
- [Explore Computational Tiers →](../computational-tiers.md)
381+
382+
---
383+
384+
💡 **Tip:** Start with simple notebook embedding and gradually add complexity. Always test your embedded notebooks in the final publication environment. Follow these notebook embedding best practices:
385+
386+
- **Pre-execute notebooks**: Always upload notebooks with outputs included
387+
- **Version control**: Use Curvenote's versioning for tracking changes
388+
- **Interactive content**: Leverage supported libraries for engaging visualizations
389+
- **Performance**: Optimize notebooks for web display and loading
390+
- **Collaboration**: Use shared workflows for team development
391+
- **Reproducibility**: Ensure all dependencies and data sources are documented

0 commit comments

Comments
 (0)