From 83c72c8b9f58d2a08a0b74ba1fe34dc7c42a677c Mon Sep 17 00:00:00 2001 From: "behinger (s-ccs 001)" Date: Thu, 21 Sep 2023 08:51:15 +0000 Subject: [PATCH] added projectworks, ohmyrepl, first docs --- _quarto.yml | 2 + installation/julia.qmd | 22 ++++++ material/3_wed/docs/handout.qmd | 38 ++++++++++ material/3_wed/docs/slides.qmd | 127 ++++++++++++++++++++++++++++++++ 4 files changed, 189 insertions(+) create mode 100644 material/3_wed/docs/slides.qmd diff --git a/_quarto.yml b/_quarto.yml index a5009d2..4d7be47 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -23,6 +23,8 @@ website: text: "Installation" - href: schedule.qmd text: "📓 Schedule" + - href: projectwork.qmd + text: "🛠 Projects" - href: social.qmd text: ":fire: Social" - section: "Cheatsheets" diff --git a/installation/julia.qmd b/installation/julia.qmd index d5f7f62..abad0e3 100644 --- a/installation/julia.qmd +++ b/installation/julia.qmd @@ -20,3 +20,25 @@ Next, install the Julia extension Finally press `Ctrl + Shift + P` to get VSCodes command palette, and type in `Julia: Start REPL` ![](https://juliateachingctu.github.io/Julia-for-Optimization-and-Learning/stable/installation/vscodeext_2.png) + + +# Optional: OhMyREPL +Optionally you cann install a package to give you nicer syntax highlighting in the REPL. + +1. Install the package: +`]activate` (without a path after activate, you activate the "global" environment) +`]add OhMyREPL` + +2. Add it to your `startup.jl` +Open `.julia/config/startup.jl` or `c:/users/USERNAME/.julia/config/startup.jl` on windows and add +```julia +atreplinit() do repl + try + @eval using OhMyREPL + catch e + @warn "error while importing OhMyREPL" e + end +end +``` + +:tada: ![](https://kristofferc.github.io/OhMyREPL.jl/latest/features/rainbow_brackets.png) \ No newline at end of file diff --git a/material/3_wed/docs/handout.qmd b/material/3_wed/docs/handout.qmd index e69de29..5611f03 100644 --- a/material/3_wed/docs/handout.qmd +++ b/material/3_wed/docs/handout.qmd @@ -0,0 +1,38 @@ + +# Documenter.jl + +### File-structure overview + +``` +Example/ +├── Project.toml +├── README.md +├── LICENSE.md +├── src +│ ├── Example.jl +│ └── utilities.jl +└── docs + ├── Project.toml + ├── src + │ ├── assets + │ │ ├── favicon.ico + │ │ └── logo.svg + │ ├── index.md + │ └── showcase.md + └── make.jl +``` + +### The `make.jl` file +```julia +using Documenter, Example +makedocs( + sitename = "Example.jl", + modules = [Example], + pages = Any[ + "Home" => "index.md", + "Showcase" => "showcase.md", + ], +) +``` +### How to generate + `julia --project=docs/ docs/make.jl` or `]activate docs/; include("make.jl")` or use `LiveServer.jl` \ No newline at end of file diff --git a/material/3_wed/docs/slides.qmd b/material/3_wed/docs/slides.qmd new file mode 100644 index 0000000..a7a752a --- /dev/null +++ b/material/3_wed/docs/slides.qmd @@ -0,0 +1,127 @@ +--- +format: revealjs +--- + +# Why documentation? + +> If people don't know why your project exists, they won't use it. If people can't figure out how to install your code, they won't use it. If people can't figure out how to use your code, they won't use it. + +## What should documentation be like? + +- ARID ("Accept (some) Repetition in Documentation") + - Not like code (for code: DRY - "don't repeat yourself") + - Repetition from code to docs is OK +- Skimmable + - Headings: descriptive, concise + - Rather use listings / "wall of text" + - Add examples +- Best: Link to other functions (discoverability) + +# Types of Documentation + +## README.md + +- **always** have a README file + +- What problem the project solves + +- Code example (best with screenshot) + +- Support / Issue-tracker + +- Contribution Guide + +- Installation instruction + +- License + +- (Roadmap) + +- (Acknowledgement) + +[A template Readme](https://github.com/othneildrew/Best-README-Template/tree/master) + +## Changelog.md + +``` +# Changelog + +## v1.0.0 +### Breaking +- *Removed* function X (@behinger) +- *Deprecated* Y (@contributor) +- *Changed* input to Z (#143) + +### Minor +- *Fixed* typos in docs +- *Added* new feature :tada: +- *Security* issue found. No fix yet +``` + +## Errormessages + +|dont|rather +|---|---| +| Input Error | Input Error: `x` was not a `Float64`, please check you didn't provide an integer | +| This should never have happened | `XYZ` was not fullfilled, please reach out as this should not have happened| + +- Provide context +- Provide advice +- Check your tone + +[more advise on writethedocs.org](https://www.writethedocs.org/guide/writing/style-guides/#error-messages) + + +## Docstrings + +``` julia +""" + radius(H::Hyperrectangle, [p]::Real=Inf)::Real + +Return the radius of a hyperrectangle. + +# Arguments + +- `H` -- hyperrectangle +- `p` -- (optional, default: `Inf`) norm + +# Output + +A real number representing the radius. + +# Notes + +The radius is defined as the radius of the enclosing ball of the given +`p`-norm of minimal volume with the same center. + +# Examples + +```julia-repl +julia> bar([1, 2], [1, 2]) +1 +\``` + +See also [`bar!`](@ref), [`baz`](@ref), [`baaz`](@ref). +""" +function radius(H::Hyperrectangle, p::Real=Inf)::Real + ... +end +``` + +Use a template and add it to all your functions + +[Julia Documentation Guide](https://docs.julialang.org/en/v1/manual/documentation/#Writing-Documentation) + +## The Manual + +A recommended system for documentation ![](https://documentation.divio.com/_images/overview.png) + +## Example: A cookbook-toolbox + +| Tutorials | How-To | Reference | Explanation | +|------------------|------------------|------------------|------------------| +| teaching a child to cook | several recipes | how ginger is added to the pot | why garlic is needed in all cookingh | +| a lesson | a series of steps | dry description | discursive explanation | +| beginners/users | users | developers | users/developers | + +Check out the [extended guide on divio.com](https://documentation.divio.com/) \ No newline at end of file