From a65ca871be54a1680f67cc4ebfcdda2c1870c477 Mon Sep 17 00:00:00 2001 From: Ludovic Raess Date: Tue, 7 Nov 2023 15:17:22 +0100 Subject: [PATCH] Fix naming confusion --- slide-notebooks/l8_2-doc.jl | 203 -------------- slide-notebooks/l9_2-doc.jl | 64 ++--- slide-notebooks/notebooks/l8_2-doc.ipynb | 329 ----------------------- slide-notebooks/notebooks/l9_2-doc.ipynb | 77 +++--- website/_literate/l8_2-doc_web.jl | 205 -------------- website/_literate/l9_2-doc_web.jl | 64 ++--- 6 files changed, 85 insertions(+), 857 deletions(-) delete mode 100644 slide-notebooks/l8_2-doc.jl delete mode 100644 slide-notebooks/notebooks/l8_2-doc.ipynb delete mode 100644 website/_literate/l8_2-doc_web.jl diff --git a/slide-notebooks/l8_2-doc.jl b/slide-notebooks/l8_2-doc.jl deleted file mode 100644 index a7cac852..00000000 --- a/slide-notebooks/l8_2-doc.jl +++ /dev/null @@ -1,203 +0,0 @@ -#src # This is needed to make this run as normal Julia file -using Markdown #src - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -#nb # _Lecture 8_ -md""" -# Documenting your code - -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/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) -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Why should I document my code? - -Why should I write code comments? -- ["Code Tells You How, Comments Tell You Why"](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/) - - code should be made understandable by itself, as much as possible - - comments then should be to tell the "why" you're doing something -- *but* I do a lot of structuring comments as well -- math-y variables tend to be short and need a comment as well -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "fragment"}} -md""" -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 importantly) understand what - your code is about -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation easily rots... - -Worse than no documentation/code comments is documentation which is -outdated. - -I find the best way to keep documentation up to date is: -- have documentation visible to you, e.g. GitHub README -- document what you need yourself -- use examples and run them as part of CI (doc-tests, example-scripts) -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -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 blank-line inbetween); interpreted as markdown-string -- can be attached to most things (functions, variables, modules, macros, types) -- can be queried with `?` -""" - -"Typical size of a beer crate" -const BEERBOX = 12 - -#- -?BEERBOX - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: doc-strings with examples - -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.) -""" - - -""" - transform(r, θ) - -Transform polar `(r,θ)` to cartesian coordinates `(x,y)`. - -## Example -```jldoctest -julia> transform(4.5, pi/5) -(3.6405764746872635, 2.6450336353161292) -``` -""" -transform(r, θ) = (r*cos(θ), r*sin(θ)) - -#- -?transform - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Github markdown rendering - -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) -by Ludovic (incidentally about solving PDEs on GPUs 🙂). - -- images are rendered -- in-page links are easy, e.g. `[_back to workshop material_](#workshop-material)` -- top-left has a burger-menu for page navigation -- can be edited within the web-page (pencil-icon) - -👉 this is a good and low-overhead way to produce pretty nice documentation -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Literate.jl - -There are several tools which render .jl files (with special formatting) into -markdown files. These files can then be added to Github and will be rendered there. - -- we're using [Literate.jl](https://github.com/fredrikekre/Literate.jl) -- format is described [here](https://fredrikekre.github.io/Literate.jl/v2/fileformat/) -- files stay valid Julia scripts, i.e. they can be executed without Literate.jl - - -Example -- 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) -``` -""" - -#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 - -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.9' - arch: x64 - - uses: julia-actions/cache@v1 - - uses: julia-actions/julia-buildpkg@latest - - name: run Literate - 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 - git add scripts/md/* - git commit -m "Commit markdown files fom Literate" - git push origin master -``` -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Documenter.jl - -If you want to have full-blown documentation, including, e.g., automatic API documentation generation, versioning, -then use [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). - -Examples: -- [https://docs.julialang.org/en/v1/](https://docs.julialang.org/en/v1/) -- [https://mauro3.github.io/Parameters.jl/stable/](https://mauro3.github.io/Parameters.jl/stable/) - -_**Notes:**_ -- it's geared towards Julia-packages, less for a bunch-of-scripts as in our lecture -- Documenter.jl also integrates with Literate.jl. -- 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** -""" diff --git a/slide-notebooks/l9_2-doc.jl b/slide-notebooks/l9_2-doc.jl index 3c818708..de479e22 100644 --- a/slide-notebooks/l9_2-doc.jl +++ b/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** """ diff --git a/slide-notebooks/notebooks/l8_2-doc.ipynb b/slide-notebooks/notebooks/l8_2-doc.ipynb deleted file mode 100644 index 19affa09..00000000 --- a/slide-notebooks/notebooks/l8_2-doc.ipynb +++ /dev/null @@ -1,329 +0,0 @@ -{ - "cells": [ - { - "cell_type": "markdown", - "source": [ - "_Lecture 8_\n", - "# Documenting your code\n", - "\n", - "This lecture we will learn:\n", - "- documentation vs code-comments\n", - "- why to write documentation\n", - "- GitHub tools:\n", - " - rendering of markdown files\n", - " - gh-pages\n", - "- some Julia tools:\n", - " - docstrings\n", - " - [https://github.com/fredrikekre/Literate.jl](https://github.com/fredrikekre/Literate.jl)\n", - " - [https://github.com/JuliaDocs/Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "_Lecture 8_\n", - "![comic](https://pcweenies.com/wp-content/uploads/2012/01/2012-01-12_pcw.jpg)" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Why should I document my code?\n", - "\n", - "Why should I write code comments?\n", - "- [\"Code Tells You How, Comments Tell You Why\"](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/)\n", - " - code should be made understandable by itself, as much as possible\n", - " - comments then should be to tell the \"why\" you're doing something\n", - "- *but* I do a lot of structuring comments as well\n", - "- math-y variables tend to be short and need a comment as well" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "Why should I write documentation?\n", - "- documentation should give a bigger overview of what your code does\n", - " - at the function-level (doc-strings)\n", - " - at the package-level (README, full-fledged documentation)\n", - "- to let other people and your future self (probably most importantly) understand what\n", - " your code is about" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "fragment" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation easily rots...\n", - "\n", - "Worse than no documentation/code comments is documentation which is\n", - "outdated.\n", - "\n", - "I find the best way to keep documentation up to date is:\n", - "- have documentation visible to you, e.g. GitHub README\n", - "- document what you need yourself\n", - "- use examples and run them as part of CI (doc-tests, example-scripts)" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: doc-strings\n", - "\n", - "A Julia doc-string ([Julia manual](https://docs.julialang.org/en/v1/manual/documentation/)):\n", - "- is just a string before the object (no blank-line inbetween); interpreted as markdown-string\n", - "- can be attached to most things (functions, variables, modules, macros, types)\n", - "- can be queried with `?`" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "outputs": [], - "cell_type": "code", - "source": [ - "\"Typical size of a beer crate\"\n", - "const BEERBOX = 12" - ], - "metadata": {}, - "execution_count": null - }, - { - "outputs": [], - "cell_type": "code", - "source": [ - "?BEERBOX" - ], - "metadata": {}, - "execution_count": null - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: doc-strings with examples\n", - "\n", - "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/)).\n", - "\n", - "(Run it in the REPL and copy paste to the docstring.)" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "outputs": [], - "cell_type": "code", - "source": [ - "\"\"\"\n", - " transform(r, θ)\n", - "\n", - "Transform polar `(r,θ)` to cartesian coordinates `(x,y)`.\n", - "\n", - "# Example\n", - "```jldoctest\n", - "julia> transform(4.5, pi/5)\n", - "(3.6405764746872635, 2.6450336353161292)\n", - "```\n", - "\"\"\"\n", - "transform(r, θ) = (r*cos(θ), r*sin(θ))" - ], - "metadata": {}, - "execution_count": null - }, - { - "outputs": [], - "cell_type": "code", - "source": [ - "?transform" - ], - "metadata": {}, - "execution_count": null - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: Github markdown rendering\n", - "\n", - "The easiest way to write long-form documentation is to just use GitHub's markdown rendering.\n", - "\n", - "A nice example is [this short course](https://github.com/luraess/parallel-gpu-workshop-JuliaCon21)\n", - "by Ludovic (incidentally about solving PDEs on GPUs 🙂).\n", - "\n", - "- images are rendered\n", - "- in-page links are easy, e.g. `[_back to workshop material_](#workshop-material)`\n", - "- top-left has a burger-menu for page navigation\n", - "- can be edited within the web-page (pencil-icon)\n", - "\n", - "👉 this is a good and low-overhead way to produce pretty nice documentation" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: Literate.jl\n", - "\n", - "There are several tools which render .jl files (with special formatting) into\n", - "markdown files. These files can then be added to Github and will be rendered there.\n", - "\n", - "- we're using [Literate.jl](https://github.com/fredrikekre/Literate.jl)\n", - "- format is described [here](https://fredrikekre.github.io/Literate.jl/v2/fileformat/)\n", - "- files stay valid Julia scripts, i.e. they can be executed without Literate.jl\n", - "\n", - "\n", - "Example\n", - "- 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)\n", - "- 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:\n", - "```\n", - "Literate.markdown(\"car_travels.jl\", directory_of_this_file, execute=true, documenter=false, credit=false)\n", - "```" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "But this is not automatic! Manual steps: run Literate, add files, commit and push...\n", - "\n", - "or use Github Actions..." - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "fragement" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: Automating Literate.jl\n", - "\n", - "Demonstrated in the repo [course-101-0250-00-L8Documentation.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl)\n", - "```yml\n", - "name: Run Literate.jl\n", - "# adapted from https://lannonbr.com/blog/2019-12-09-git-commit-in-actions\n", - "on: push\n", - "jobs:\n", - " lit:\n", - " runs-on: ubuntu-latest\n", - " steps:\n", - " # Checkout the branch\n", - " - uses: actions/checkout@v2\n", - " - uses: julia-actions/setup-julia@v1\n", - " with:\n", - " version: '1.9'\n", - " arch: x64\n", - " - uses: julia-actions/cache@v1\n", - " - uses: julia-actions/julia-buildpkg@latest\n", - " - name: run Literate\n", - " run: QT_QPA_PLATFORM=offscreen julia --color=yes --project -e 'cd(\"scripts\"); include(\"literate-script.jl\")'\n", - " - name: setup git config\n", - " run: |\n", - " # setup the username and email. I tend to use 'GitHub Actions Bot' with no email by default\n", - " git config user.name \"GitHub Actions Bot\"\n", - " git config user.email \"<>\"\n", - " - name: commit\n", - " run: |\n", - " # Stage the file, commit and push\n", - " git add scripts/md/*\n", - " git commit -m \"Commit markdown files fom Literate\"\n", - " git push origin master\n", - "```" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - }, - { - "cell_type": "markdown", - "source": [ - "### Documentation tools: Documenter.jl\n", - "\n", - "If you want to have full-blown documentation, including, e.g., automatic API documentation generation, versioning,\n", - "then use [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl).\n", - "\n", - "Examples:\n", - "- [https://docs.julialang.org/en/v1/](https://docs.julialang.org/en/v1/)\n", - "- [https://mauro3.github.io/Parameters.jl/stable/](https://mauro3.github.io/Parameters.jl/stable/)\n", - "\n", - "_**Notes:**_\n", - "- it's geared towards Julia-packages, less for a bunch-of-scripts as in our lecture\n", - "- Documenter.jl also integrates with Literate.jl.\n", - "- for more free-form websites, use [https://github.com/tlienart/Franklin.jl](https://github.com/tlienart/Franklin.jl) (as the course website does)\n", - "- if you want to use it, it's easiest to generate your package with [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl)\n", - " which will generate the Documenter-setup for you.\n", - "- **we don't use it in this course**" - ], - "metadata": { - "name": "A slide ", - "slideshow": { - "slide_type": "slide" - } - } - } - ], - "nbformat_minor": 3, - "metadata": { - "language_info": { - "file_extension": ".jl", - "mimetype": "application/julia", - "name": "julia", - "version": "1.9.3" - }, - "kernelspec": { - "name": "julia-1.9", - "display_name": "Julia 1.9.3", - "language": "julia" - } - }, - "nbformat": 4 -} diff --git a/slide-notebooks/notebooks/l9_2-doc.ipynb b/slide-notebooks/notebooks/l9_2-doc.ipynb index e9ece679..23c469ff 100644 --- a/slide-notebooks/notebooks/l9_2-doc.ipynb +++ b/slide-notebooks/notebooks/l9_2-doc.ipynb @@ -9,11 +9,25 @@ "This lecture we will learn:\n", "- documentation vs code-comments\n", "- why to write documentation\n", + "- GitHub tools:\n", + " - rendering of markdown files\n", + " - gh-pages\n", "- some Julia tools:\n", " - docstrings\n", - " - [https://github.com/JuliaDocs/Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)\n", " - [https://github.com/fredrikekre/Literate.jl](https://github.com/fredrikekre/Literate.jl)\n", - "\n", + " - [https://github.com/JuliaDocs/Documenter.jl](https://github.com/JuliaDocs/Documenter.jl)" + ], + "metadata": { + "name": "A slide ", + "slideshow": { + "slide_type": "slide" + } + } + }, + { + "cell_type": "markdown", + "source": [ + "_Lecture 8_\n", "![comic](https://pcweenies.com/wp-content/uploads/2012/01/2012-01-12_pcw.jpg)" ], "metadata": { @@ -49,7 +63,7 @@ "- documentation should give a bigger overview of what your code does\n", " - at the function-level (doc-strings)\n", " - at the package-level (README, full-fledged documentation)\n", - "- to let other people and your future self (probably most important) understand what\n", + "- to let other people and your future self (probably most importantly) understand what\n", " your code is about" ], "metadata": { @@ -85,7 +99,7 @@ "### Documentation tools: doc-strings\n", "\n", "A Julia doc-string ([Julia manual](https://docs.julialang.org/en/v1/manual/documentation/)):\n", - "- is just a string before the object (no new-line); interpreted as markdown-string\n", + "- is just a string before the object (no blank-line inbetween); interpreted as markdown-string\n", "- can be attached to most things (functions, variables, modules, macros, types)\n", "- can be queried with `?`" ], @@ -100,14 +114,7 @@ "outputs": [], "cell_type": "code", "source": [ - "\"\"\"\n", - " transform(r, θ) = (r*cos(θ), r*sin(θ))\n", - "\n", - "Transform polar to cartesian coordinates.\n", - "\"\"\"\n", - "transform(r, θ) = (r*cos(θ), r*sin(θ))\n", - "\n", - "\"Typical size of beer crate\"\n", + "\"Typical size of a beer crate\"\n", "const BEERBOX = 12" ], "metadata": {}, @@ -129,7 +136,7 @@ "\n", "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/)).\n", "\n", - "- run it in the REPL and copy paste to the docstring" + "(Run it in the REPL and copy paste to the docstring.)" ], "metadata": { "name": "A slide ", @@ -143,9 +150,9 @@ "cell_type": "code", "source": [ "\"\"\"\n", - " transform(r, θ) = (r*cos(θ), r*sin(θ))\n", + " transform(r, θ)\n", "\n", - "Transform polar to cartesian coordinates.\n", + "Transform polar `(r,θ)` to cartesian coordinates `(x,y)`.\n", "\n", "# Example\n", "```jldoctest\n", @@ -174,7 +181,7 @@ "\n", "The easiest way to write long-form documentation is to just use GitHub's markdown rendering.\n", "\n", - "A nice example is [this short course](https://github.com/luraess/parallel-gpu-workshop-JuliaCon21#parallel-cpu-implementation)\n", + "A nice example is [this short course](https://github.com/luraess/parallel-gpu-workshop-JuliaCon21)\n", "by Ludovic (incidentally about solving PDEs on GPUs 🙂).\n", "\n", "- images are rendered\n", @@ -205,8 +212,8 @@ "\n", "\n", "Example\n", - "- 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)\n", - "- 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)\n", + "- 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)\n", + "- 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:\n", "```\n", "Literate.markdown(\"car_travels.jl\", directory_of_this_file, execute=true, documenter=false, credit=false)\n", "```" @@ -221,7 +228,9 @@ { "cell_type": "markdown", "source": [ - "But this is not automatic! Manual steps: run Literate, add files, commit and push..." + "But this is not automatic! Manual steps: run Literate, add files, commit and push...\n", + "\n", + "or use Github Actions..." ], "metadata": { "name": "A slide ", @@ -235,47 +244,30 @@ "source": [ "### Documentation tools: Automating Literate.jl\n", "\n", - "As is done on [course-101-0250-00-L8Documentation.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl)\n", + "Demonstrated in the repo [course-101-0250-00-L8Documentation.jl](https://github.com/eth-vaw-glaciology/course-101-0250-00-L8Documentation.jl)\n", "```yml\n", "name: Run Literate.jl\n", "# adapted from https://lannonbr.com/blog/2019-12-09-git-commit-in-actions\n", - "\n", "on: push\n", - "\n", "jobs:\n", " lit:\n", " runs-on: ubuntu-latest\n", " steps:\n", " # Checkout the branch\n", " - uses: actions/checkout@v2\n", - "\n", " - uses: julia-actions/setup-julia@v1\n", " with:\n", - " version: '1.8'\n", + " version: '1.9'\n", " arch: x64\n", - "\n", - " - uses: actions/cache@v1\n", - " env:\n", - " cache-name: cache-artifacts\n", - " with:\n", - " path: ~/.julia/artifacts\n", - " key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}\n", - " restore-keys: |\n", - " ${{ runner.os }}-test-${{ env.cache-name }}-\n", - " ${{ runner.os }}-test-\n", - " ${{ runner.os }}-\n", - "\n", - " - uses: julia-actions/julia-buildpkg@v1\n", - "\n", + " - uses: julia-actions/cache@v1\n", + " - uses: julia-actions/julia-buildpkg@latest\n", " - name: run Literate\n", - " run: julia --color=yes --project -e 'cd(\"scripts\"); include(\"literate-script.jl\")'\n", - "\n", + " run: QT_QPA_PLATFORM=offscreen julia --color=yes --project -e 'cd(\"scripts\"); include(\"literate-script.jl\")'\n", " - name: setup git config\n", " run: |\n", " # setup the username and email. I tend to use 'GitHub Actions Bot' with no email by default\n", " git config user.name \"GitHub Actions Bot\"\n", " git config user.email \"<>\"\n", - "\n", " - name: commit\n", " run: |\n", " # Stage the file, commit and push\n", @@ -308,7 +300,8 @@ "- Documenter.jl also integrates with Literate.jl.\n", "- for more free-form websites, use [https://github.com/tlienart/Franklin.jl](https://github.com/tlienart/Franklin.jl) (as the course website does)\n", "- if you want to use it, it's easiest to generate your package with [PkgTemplates.jl](https://github.com/invenia/PkgTemplates.jl)\n", - " which will generate the Documenter-setup for you." + " which will generate the Documenter-setup for you.\n", + "- **we don't use it in this course**" ], "metadata": { "name": "A slide ", diff --git a/website/_literate/l8_2-doc_web.jl b/website/_literate/l8_2-doc_web.jl deleted file mode 100644 index 476c8542..00000000 --- a/website/_literate/l8_2-doc_web.jl +++ /dev/null @@ -1,205 +0,0 @@ -#src # This is needed to make this run as normal Julia file -using Markdown #src - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -#nb # _Lecture 8_ -md""" -# Documenting your code - -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/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) -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Why should I document my code? - -Why should I write code comments? -- ["Code Tells You How, Comments Tell You Why"](https://blog.codinghorror.com/code-tells-you-how-comments-tell-you-why/) - - code should be made understandable by itself, as much as possible - - comments then should be to tell the "why" you're doing something -- *but* I do a lot of structuring comments as well -- math-y variables tend to be short and need a comment as well -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "fragment"}} -md""" -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 importantly) understand what - your code is about -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation easily rots... - -Worse than no documentation/code comments is documentation which is -outdated. - -I find the best way to keep documentation up to date is: -- have documentation visible to you, e.g. GitHub README -- document what you need yourself -- use examples and run them as part of CI (doc-tests, example-scripts) -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -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 blank-line inbetween); interpreted as markdown-string -- can be attached to most things (functions, variables, modules, macros, types) -- can be queried with `?` -""" - -"Typical size of a beer crate" -const BEERBOX = 12 - -#- -?BEERBOX - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: doc-strings with examples - -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.) -""" - - -""" - transform(r, θ) - -Transform polar `(r,θ)` to cartesian coordinates `(x,y)`. - -## Example -```jldoctest -julia> transform(4.5, pi/5) -(3.6405764746872635, 2.6450336353161292) -``` -""" -transform(r, θ) = (r*cos(θ), r*sin(θ)) - -#- -?transform - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Github markdown rendering - -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) -by Ludovic (incidentally about solving PDEs on GPUs 🙂). - -- images are rendered -- in-page links are easy, e.g. `[_back to workshop material_](#workshop-material)` -- top-left has a burger-menu for page navigation -- can be edited within the web-page (pencil-icon) - -👉 this is a good and low-overhead way to produce pretty nice documentation -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Literate.jl - -There are several tools which render .jl files (with special formatting) into -markdown files. These files can then be added to Github and will be rendered there. - -- we're using [Literate.jl](https://github.com/fredrikekre/Literate.jl) -- format is described [here](https://fredrikekre.github.io/Literate.jl/v2/fileformat/) -- files stay valid Julia scripts, i.e. they can be executed without Literate.jl - - -Example -- 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) -``` -""" - -#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 - -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.9' - arch: x64 - - uses: julia-actions/cache@v1 - - uses: julia-actions/julia-buildpkg@latest - - name: run Literate - 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 - git add scripts/md/* - git commit -m "Commit markdown files fom Literate" - git push origin master -``` -""" - -#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}} -md""" -### Documentation tools: Documenter.jl - -If you want to have full-blown documentation, including, e.g., automatic API documentation generation, versioning, -then use [Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). - -Examples: -- [https://docs.julialang.org/en/v1/](https://docs.julialang.org/en/v1/) -- [https://mauro3.github.io/Parameters.jl/stable/](https://mauro3.github.io/Parameters.jl/stable/) - -_**Notes:**_ -- it's geared towards Julia-packages, less for a bunch-of-scripts as in our lecture -- Documenter.jl also integrates with Literate.jl. -- 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** -""" - - diff --git a/website/_literate/l9_2-doc_web.jl b/website/_literate/l9_2-doc_web.jl index 2a1da8b1..e81bd7f4 100644 --- a/website/_literate/l9_2-doc_web.jl +++ b/website/_literate/l9_2-doc_web.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,6 +199,7 @@ _**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** """