Skip to content

Commit b0c62c7

Browse files
committed
Update README
Mainly the structure, adding tutorials, publishing updates sections for clarity and to match most recent folder reorg.
1 parent 57f8c9c commit b0c62c7

File tree

1 file changed

+56
-28
lines changed

1 file changed

+56
-28
lines changed

README.md

Lines changed: 56 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This repository contains the source code for a [set of tutorials](https://juliaa
66

77
You can read the tutorials [online](https://juliaai.github.io/DataScienceTutorials.jl/).
88

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.
1010

1111
To do so, save both files in an appropriate folder, start Julia, `cd` to the folder and
1212

@@ -23,57 +23,85 @@ Pkg.instantiate()
2323
The rest of these instructions assume that you've cloned the package and have `cd` to it.
2424

2525
### 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/)
2849

2950
### Fixing an existing tutorial
3051

31-
Find the corresponding script, fix it in a PR.
52+
Find the corresponding Julia script in `_literate` and fix it in a PR.
3253

3354
### Add a new tutorial
3455

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.
4158
* 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, ...)
4360
* 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.
4464

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:
4666

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")
4872

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()
5276

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.
5381

5482
### Publishing updates
5583

5684
**Assumptions**:
5785

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
5987

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/)
6189
matches the version used to generate the web-site (which should
6290
match the version declared in each tutorial's Manifest.toml file)
6391

6492

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:**
7094

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
7498
using NodeJS
7599
run(`sudo $(npm_cmd()) i lunr cheerio`)
76100
```
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+
77105

78106
This should take ≤ 15 seconds to complete.
79107

@@ -139,9 +167,9 @@ serve(; eval_all=true)
139167

140168
note that this will take a while.
141169

142-
#### Merge conflicts
170+
#### Merge conflicts or Missing Styles
143171

144-
If you get merge conflicts, do
172+
If you get merge conflicts or have styles that seem to be missing after `serve()`, do
145173

146174
```julia
147175
cleanpull()

0 commit comments

Comments
 (0)