Fix naming confusion

slide-notebooks/l9_2-doc.jl

@@ -9,11 +9,18 @@ md"""
 This lecture we will learn:
 - documentation vs code-comments
 - why to write documentation
+- GitHub tools:
+  - rendering of markdown files
+  - gh-pages
 - some Julia tools:
   - docstrings
-  - [https://github.com/JuliaDocs/Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)
   - [https://github.com/fredrikekre/Literate.jl](https://github.com/fredrikekre/Literate.jl)
+  - [https://github.com/JuliaDocs/Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)
+"""
 
+#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+#nb # _Lecture 8_
+md"""
 ![comic](https://pcweenies.com/wp-content/uploads/2012/01/2012-01-12_pcw.jpg)
 """
 
@@ -35,7 +42,7 @@ Why should I write documentation?
 - documentation should give a bigger overview of what your code does
   - at the function-level (doc-strings)
   - at the package-level (README, full-fledged documentation)
-- to let other people and your future self (probably most important) understand what
+- to let other people and your future self (probably most importantly) understand what
   your code is about
 """
 
@@ -57,19 +64,12 @@ md"""
 ### Documentation tools: doc-strings
 
 A Julia doc-string ([Julia manual](https://docs.julialang.org/en/v1/manual/documentation/)):
-- is just a string before the object (no new-line); interpreted as markdown-string
+- is just a string before the object (no blank-line inbetween); interpreted as markdown-string
 - can be attached to most things (functions, variables, modules, macros, types)
 - can be queried with `?`
 """
 
-"""
-    transform(r, θ) = (r*cos(θ), r*sin(θ))
-
-Transform polar to cartesian coordinates.
-"""
-transform(r, θ) = (r*cos(θ), r*sin(θ))
-
-"Typical size of beer crate"
+"Typical size of a beer crate"
 const BEERBOX = 12
 
 #-
@@ -81,14 +81,14 @@ md"""
 
 One can add examples to doc-strings (they can even be part of testing: [doc-tests](https://juliadocs.github.io/Documenter.jl/stable/man/doctests/)).
 
-- run it in the REPL and copy paste to the docstring
+(Run it in the REPL and copy paste to the docstring.)
 """
 
 
 """
-    transform(r, θ) = (r*cos(θ), r*sin(θ))
+    transform(r, θ)
 
-Transform polar to cartesian coordinates.
+Transform polar `(r,θ)` to cartesian coordinates `(x,y)`.
 
 ## Example
 ```jldoctest
@@ -107,7 +107,7 @@ md"""
 
 The easiest way to write long-form documentation is to just use GitHub's markdown rendering.
 
-A nice example is [this short course](https://github.com/luraess/parallel-gpu-workshop-JuliaCon21#parallel-cpu-implementation)
+A nice example is [this short course](https://github.com/luraess/parallel-gpu-workshop-JuliaCon21)
 by Ludovic (incidentally about solving PDEs on GPUs 🙂).
 
 - images are rendered
@@ -131,8 +131,8 @@ markdown files.  These files can then be added to Github and will be rendered th
 
 
 Example
-- output markdown in: [course-101-0250-00-L8Documentation.jl: scripts/car_travels.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl/blob/4bbeb3ddda046490847f050b02d3fc5d9308695b/scripts/car_travels.jl)
-- output markdown in: [course-101-0250-00-L8Documentation.jl: scripts/car_travels.md](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl/blob/4bbeb3ddda046490847f050b02d3fc5d9308695b/scripts/car_travels.md)
+- input julia-code in: [course-101-0250-00-L8Documentation.jl: scripts/car_travels.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl/blob/4bbeb3ddda046490847f050b02d3fc5d9308695b/scripts/car_travels.jl)
+- output markdown in: [course-101-0250-00-L8Documentation.jl: scripts/car_travels.md](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl/blob/4bbeb3ddda046490847f050b02d3fc5d9308695b/scripts/car_travels.md) created with:
 ```
 Literate.markdown("car_travels.jl", directory_of_this_file, execute=true, documenter=false, credit=false)
 ```
@@ -141,53 +141,38 @@ Literate.markdown("car_travels.jl", directory_of_this_file, execute=true, docume
 #nb # %% A slide [markdown] {"slideshow": {"slide_type": "fragement"}}
 md"""
 But this is not automatic!  Manual steps: run Literate, add files, commit and push...
+
+or use Github Actions...
 """
 
 #nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 md"""
 ### Documentation tools: Automating Literate.jl
 
-As is done on [course-101-0250-00-L8Documentation.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl)
+Demonstrated in the repo [course-101-0250-00-L8Documentation.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl)
 ```yml
 name: Run Literate.jl
 # adapted from https://lannonbr.com/blog/2019-12-09-git-commit-in-actions
-
 on: push
-
 jobs:
   lit:
     runs-on: ubuntu-latest
     steps:
       # Checkout the branch
       - uses: actions/checkout@v2
-
       - uses: julia-actions/setup-julia@v1
         with:
-          version: '1.8'
+          version: '1.9'
           arch: x64
-
-      - uses: actions/cache@v1
-        env:
-          cache-name: cache-artifacts
-        with:
-          path: ~/.julia/artifacts
-          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-test-${{ env.cache-name }}-
-            ${{ runner.os }}-test-
-            ${{ runner.os }}-
-
-      - uses: julia-actions/julia-buildpkg@v1
-
+      - uses: julia-actions/cache@v1
+      - uses: julia-actions/julia-buildpkg@latest
       - name: run Literate
-        run: julia --color=yes --project -e 'cd("scripts"); include("literate-script.jl")'
-
+        run: QT_QPA_PLATFORM=offscreen julia --color=yes --project -e 'cd("scripts"); include("literate-script.jl")'
       - name: setup git config
         run: |
           # setup the username and email. I tend to use 'GitHub Actions Bot' with no email by default
           git config user.name "GitHub Actions Bot"
           git config user.email "<>"
-
       - name: commit
         run: |
           # Stage the file, commit and push
@@ -214,4 +199,5 @@ _**Notes:**_
 - for more free-form websites, use [https://github.com/tlienart/Franklin.jl](https://github.com/tlienart/Franklin.jl) (as the course website does)
 - if you want to use it, it's easiest to generate your package with [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl)
   which will generate the Documenter-setup for you.
+- **we don't use it in this course**
 """