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
+56-28Lines changed: 56 additions & 28 deletions
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ This repository contains the source code for a [set of tutorials](https://juliaa
6
6
7
7
You can read the tutorials [online](https://juliaai.github.io/DataScienceTutorials.jl/).
8
8
9
-
You can find a runnable script for each tutorial at the top of each tutorial page along with a `Project.toml` and a `Manifest.toml` you can use to re-create the exact environment that was used to run the tutorial.
9
+
You can find a runnable script for each tutorial linked at the top of each tutorial page along with a `Project.toml` and a `Manifest.toml` you can use to re-create the exact environment that was used to run the tutorial.
10
10
11
11
To do so, save both files in an appropriate folder, start Julia, `cd` to the folder and
12
12
@@ -23,57 +23,85 @@ Pkg.instantiate()
23
23
The rest of these instructions assume that you've cloned the package and have `cd` to it.
24
24
25
25
### Structure
26
-
27
-
All tutorials correspond to a Literate script that's in `_literate/`.
26
+
The following are the folders relevant to pages on the website:
27
+
```
28
+
├── _literate
29
+
│ ├── data # has "Data Basics" tutorials
30
+
│ ├── getting-started # has "Getting Started" tutorials
31
+
│ ├── isl # has "Introduction to Statistical Learning" tutorials
32
+
│ ├── end-to-end # has "End-to-End" tutorials
33
+
│ └── advanced # has "Advanced" tutorials
34
+
├── data # This and the four folders below import content from "_literate" to the website
35
+
├── getting-started
36
+
├── isl
37
+
├── end-to-end
38
+
├── advanced
39
+
├── info # has markdown files corresponding to info pages
40
+
├── index.md # has markdown for the landing page
41
+
├── search.md # has markdown for the search page
42
+
├── routes.json # has all the navigation bar data
43
+
├── collapse-script.jl # script that adds dropdowns to tutorials
44
+
├── deploy.jl # deployment script
45
+
├── Manifest.toml
46
+
└── Project.toml # Project's environment
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/)
28
49
29
50
### Fixing an existing tutorial
30
51
31
-
Find the corresponding script, fix it in a PR.
52
+
Find the corresponding Julia script in `_literate` and fix it in a PR.
32
53
33
54
### Add a new tutorial
34
55
35
-
* Duplicate the folder `EX-wine`.
36
-
* Change its name:
37
-
*`EX-somename` for an "end-to-end" tutorial `somename`
38
-
*`A-somename` for a "getting started" tutorial `somename`
39
-
*`D0-somename` for a "data" tutorial `somename`
40
-
*`ISL-lab-x` for an "Introduction to Statistical Learning" tutorial
56
+
* Go to the appropriate folder inside `_literate` depending on the category of the tutorial as described above
57
+
* Duplicate one of the tutorials as a starting point.
41
58
* Remove `Manifest.toml` and `Project.toml`
42
-
*Activate that folder and add the packages that you'll need (MLJ, ...)
59
+
*Create and activate an environment in that folder and add the packages that you'll need (MLJ, ...)
43
60
* Write your tutorial following the blueprint
61
+
* Run `julia collapse-script.jl` to add necessary Franklin syntax to your tutorial to make sections in it collapsible like other tutorials
62
+
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.
44
64
45
-
**Note**: your tutorial **must** "just work" otherwise it will be ignored, in other words, we should be able to just copy the folder containing your `.jl` and `.toml` files, and run it without having to do anything special.
65
+
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:
46
66
47
-
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 in the previous step you'd have `EX-dinosaurs` and you would
67
+
* 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
+
* 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:
70
+
```julia
71
+
cd("path/to/DataScienceTutorials")
48
72
49
-
* create a file `dinosaurs.md` in `end-to-end/` by duplicating the `end-to-end/wine.md` and changing the reference in it to `\tutorial{EX-dinosaurs}`
50
-
* add a link pointing to that tutorial in `_libs/nav/head.js` following the template so your tutorial shows in the navigation bar
51
-
* lastly, to make sections in your tutorial collapsible like other tutorials run the `collapse-script.jl` file via `julia collapse-script.jl`
73
+
using Pkg
74
+
Pkg.activate(".")
75
+
Pkg.instantiate()
52
76
77
+
using Franklin
78
+
serve() # serve the website locally
79
+
```
80
+
This may generate some files under `__site`. Don't push them in your PR.
53
81
54
82
### Publishing updates
55
83
56
84
**Assumptions**:
57
85
58
-
* you have a PR with changes, someone has reviewed them and they got merged into the main branch
86
+
* you have a PR with changes, someone has reviewed them and they got merged into the master branch
59
87
60
-
* Be sure the version of Julia declared near the top of `index.md`
88
+
* Be sure the version of Julia declared [here](https://juliaai.github.io/DataScienceTutorials.jl/how-to-run-code/)
61
89
matches the version used to generate the web-site (which should
62
90
match the version declared in each tutorial's Manifest.toml file)
63
91
64
92
65
-
**Once the changes are in the main branch**:
66
-
67
-
* run `cd("path/to/DataScienceTutorials"); using Franklin` to launch Franklin
68
-
* run `serve(single=true, verb=true)` to ensure no issues generating the relevant html pages with code block evaluations, and then run `serve()` (after restarting) to serve the pages live on a local browser for viewing
69
-
* run `include("deploy.jl")` to re-generate the LUNR index and push the changes to GitHub.
93
+
**Once the changes are in the master branch:**
70
94
71
-
The second step requires you have `lunr` and `cheerio` installed, if not:
72
-
73
-
```
95
+
* Run `cd("path/to/DataScienceTutorials"); using Franklin` to launch Franklin
96
+
* In case you don't have `lunr` and `cheerio` installed already, also do:
97
+
```julia
74
98
using NodeJS
75
99
run(`sudo $(npm_cmd()) i lunr cheerio`)
76
100
```
101
+
* Run `serve(single=true, verb=true)` to ensure no issues generating the relevant html pages with code block evaluations
102
+
* Run `serve()` (after restarting) to serve the pages live on a local browser for viewing
103
+
* run `include("deploy.jl")` which re-generates the LUNR index and automatically pushes the changes to GitHub.
104
+
77
105
78
106
This should take ≤ 15 seconds to complete.
79
107
@@ -139,9 +167,9 @@ serve(; eval_all=true)
139
167
140
168
note that this will take a while.
141
169
142
-
#### Merge conflicts
170
+
#### Merge conflicts or Missing Styles
143
171
144
-
If you get merge conflicts, do
172
+
If you get merge conflicts or have styles that seem to be missing after `serve()`, do
0 commit comments