summerschool_simtech_2023/material/3_wed/docs/handout.qmd

---

---

::: callout
[Link to Slides](slides.qmd)
:::

## Task 1

Solve [task 1](tasks.qmd#1)

----

# 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
 - `LiveServer.jl` + `deploydocs()`

### How to write

```julia
# Normal Markdown is great
Also write lots of text

```@example Main
a = 1
    ```

More text!

```@example Main
b = a
    ```


```@example NewScope
a = 3 # a new a appears!
    ```
 
```

# Bonus: Literate.jl 
Using `Literate.jl` one does not need to write `.md` files - but rather can use `.jl` files that are translated to `.md` files.

```julia
# # This is markdown headline
# This is normal markdown code
1 ==1

# Be careful in forloops with comments, Literate
## this is a comment
```


## Task 2

Solve [task 2](tasks.qmd#2)

----

# PkgTemplate.jl 
```julia
]activate --temp
]add PkgTemplates
using PkgTemplates
tpl = Template(user="yourGithubUser",
            dir="./PkgTemplate", # the new package will appear in this folder
            plugins=[GitHubActions(;extra_versions=["nightly"]),Documenter{GitHubActions}()])
tpl("MyStatisticsPackage") # created in ./PkgTemplate/MyStatisticsPackage/Project.toml
```


This will create the Project+Git, but also setup github-actions / ContinuousIntegration with tests and docs.

You still need to go to [github.com](https://github.com) (or use `gh repo create` with the [gh-command line interface](https://cli.github.com/)) and create an not-initialized / empty repository with the same name (but .jl added), and run 
```julia
git remote add origin https://github.com/behinger/MyStatisticsPackage.jl
git push -u origin main
```

Finally, to activate documentation being deployed, you need to go to your Github-Repo, go to Settings, Pages and select the gh_page branch to be deployed.

::: callout-tip
You can also run the PkgTemplate interactively using
```julia
  Template(interactive=true)("MyPkg")
```
Which will ask you a hundred million questions ;-)
::: 


## Task 3

Solve [task 3](tasks.qmd#3)