You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+54-58Lines changed: 54 additions & 58 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,8 @@
1
1
# DataScienceTutorials.jl
2
2
3
-
This repository contains the source code for a [set of tutorials](https://juliaai.github.io/DataScienceTutorials.jl/) introducing the use of Julia and Julia packages such as MLJ (but not only) to do "data science" in Julia.
3
+
This repository contains the source code for a [set of tutorials](https://juliaai.github.io/DataScienceTutorials.jl/) introducing the use of Julia and Julia packages such as MLJ, among others, to do "data science" in Julia.
4
4
5
-
## For readers
5
+
## 📖 For readers
6
6
7
7
You can read the tutorials [online](https://juliaai.github.io/DataScienceTutorials.jl/).
8
8
@@ -18,11 +18,11 @@ Pkg.instantiate()
18
18
19
19
**Note**: you are strongly encouraged to [open issues](https://github.com/juliaai/DataScienceTutorials.jl/issues/new) on this repository indicating points that are unclear or could be better explained, help us have great tutorials!
20
20
21
-
## For developers
21
+
## 👩💻 For developers
22
22
23
23
The rest of these instructions assume that you've cloned the package and have `cd` to it.
24
24
25
-
### Structure
25
+
### 📂 Structure
26
26
The following are the folders relevant to pages on the website:
27
27
```
28
28
├── _literate
@@ -40,18 +40,20 @@ The following are the folders relevant to pages on the website:
40
40
├── index.md # has markdown for the landing page
41
41
├── search.md # has markdown for the search page
42
42
├── routes.json # has all the navigation bar data
43
-
├── collapse-script.jl # script that adds dropdowns to tutorials
43
+
├── collapse-script.jl # script that adds collapsible sections to tutorials
44
44
├── deploy.jl # deployment script
45
45
├── Manifest.toml
46
-
└── Project.toml # Project's environment
46
+
└── Project.toml # For the project's environment
47
47
```
48
-
To understand the rest of the structure which could help you change styles with CSS or add interaction with JavaScript read the relevant page on [Franklin's documentation](https://franklinjl.org/workflow/)
48
+
To understand the rest of the structure which could help you change styles with CSS or add interaction with JavaScript read the relevant page on [Franklin's documentation](https://franklinjl.org/workflow/).
49
49
50
-
### Fixing an existing tutorial
50
+
### 👨🏻🔧 Modifying an existing tutorial
51
51
52
-
Find the corresponding Julia script in `_literate` and fix it in a PR.
52
+
* Find the corresponding Julia script in `_literate` and fix it in a PR.
53
+
* Ensure it works and renders properly as explained in [this section](#👀-visualise-modifications-locally).
53
54
54
-
### Add a new tutorial
55
+
56
+
### ✨ Add a new tutorial
55
57
56
58
* Go to the appropriate folder inside `_literate` depending on the category of the tutorial as described above
57
59
* Duplicate one of the tutorials as a starting point.
@@ -60,26 +62,59 @@ Find the corresponding Julia script in `_literate` and fix it in a PR.
60
62
* Write your tutorial following the blueprint
61
63
* Run `julia collapse-script.jl` to add necessary Franklin syntax to your tutorial to make sections in it collapsible like other tutorials
62
64
63
-
**Note**: your tutorial **must** "just work" otherwise it will be ignored, in other words, any Julia user should be able to just copy the folder containing your `.jl` and `.toml` files, and run it without having to do anything special.
65
+
> [!IMPORTANT]
66
+
> Your tutorial **must** "just work" otherwise it will be ignored, in other words, any Julia user should be able to just copy the folder containing your `.jl` and `.toml` files, and run it without having to do anything special.
64
67
65
68
Once all that's done, the remaining things to do are to create the HTML page and a link in the appropriate location. Let's assume you wanted to add an E2E tutorial "Dinosaurs" then this implies that `_literate/end-to-end/dinosaurs.jl` exists and you would:
66
69
67
70
* Create a file `dinosaurs.md` in the top-level folder `end-to-end/` by duplicating the `end-to-end/wine.md` and changing the reference in it to `\tutorial{end-to-end/dinosaurs}`
68
71
* Add a link pointing to that tutorial in `routing.json` following the template so your tutorial shows in the navigation bar
69
-
* Ensure your tutorials renders correctly by running the following:
72
+
* Ensure your tutorials renders correctly as explained in the [next section](#👀-visualise-modifications-locally).
73
+
74
+
> [!NOTE]
75
+
> For plots, we do prefer that you use `Plots.jl` with the default backend. In general, try to avoid having Python as a dependency in your tutorial.
76
+
77
+
<details>
78
+
<summary> For more information about adding plots</summary>
79
+
<br>
80
+
Follow the pattern in existing tutorials; finish a code block defining a plot with:
Here "the alt here" is the text that appears if there is problem rendering the
89
+
figure. Please do not use anything else than SVG; please also stick to
90
+
this path and start the name of the file with the name of the tutorial
91
+
(to help keep files organised).
72
92
93
+
Do not forget to add the `# hide` which will ensure the line is not displayed on the website, notebook, or script.
94
+
</details>
95
+
96
+
### 👀 Visualise modifications locally
97
+
98
+
```julia
73
99
using Pkg
74
100
Pkg.activate(".")
75
101
Pkg.instantiate()
76
102
77
103
using Franklin
78
-
serve()# serve the website locally
104
+
serve()
79
105
```
80
-
This may generate some files under `__site`. Don't push them in your PR.
81
106
82
-
### Publishing updates
107
+
This makes Franklin to re-evaluate some of the code based on the changes which may take some time, progress is indicated in the REPL. Once it finishes it will open the browser to render the website after the changes.
108
+
109
+
**Note**:
110
+
- If you decide to change some of the code while `serve()` is running, this is fine, Franklin will detect it and trigger an update of the relevant web pages (after evaluating the new code).
111
+
112
+
- This may generate some files under `__site` don't push them in your PR as they will be pushed upon deployment.
113
+
114
+
- Avoid modifying the literate file, killing the Julia session, then calling `serve()` that sequence can cause weird issues where Julia will complain about the age of the world...
115
+
116
+
117
+
### 🚀 Publishing updates
83
118
84
119
**Assumptions**:
85
120
@@ -105,47 +140,8 @@ run(`sudo $(npm_cmd()) i lunr cheerio`)
105
140
106
141
This should take ≤ 15 seconds to complete.
107
142
108
-
---
109
-
110
-
# Old instructions (still valid)
111
-
112
-
### Visualise modifications locally
113
-
114
-
```julia
115
-
cd("path/to/DataScienceTutorials")
116
-
using Franklin
117
-
serve()
118
-
```
119
-
120
-
If you have changed the *code* of some of the literate scripts, Franklin will need to re-evaluate some of the code which may take some time, progress is indicated in the REPL.
121
-
122
-
If you decide to change some of the code while `serve()` is running, this is fine, Franklin will detect it and trigger an update of the relevant web pages (after evaluating the new code).
123
-
124
-
**Notes**:
125
-
- avoid modifying the literate file, killing the Julia session, then calling `serve()` that sequence can cause weird issues where Julia will complain about the age of the world...
126
-
- the `serve()` command above activates the environment.
127
-
128
-
### Plots
129
-
130
-
For the moment, plots are done with `PyPlot.jl` (though you're not restricted to use it).
131
-
It's best not to use `Plots.jl` because the loading time would risk making full updates of the webpage annoyingly slow.
132
-
133
-
In order to display a plot, finish a code block defining a plot with
0 commit comments