Add JuliaCon2024 documentation workshop (new block 5)

CHANGELOG.md

@@ -0,0 +1,18 @@
+# CHANGELOG
+
+Changelog for this Good Scientific Code Workshop is kept with respect to version v1 (the first published version).
+
+## 1.1
+
+Drastically improved the Documentation block (block 5), in preparation for presenting it to JuliaCon 2024. The block is now more extensive with more useful information, much more examples and hyperlinks to external documentations, and much more exercises.
+
+However, it focuses more on the Julia language as it was presented at JuliaCon2024.
+For Python users, one would need to **contribute** to this repository a couple of slides that
+
+1. Add examples from excellently documented Python packages
+2. Add links to the Python go-to documentation builder (likely Sphinx)
+3. Add premade GitHub CI files for building docs on GitHub CI.
+
+As this material does not exist yet, the PDF for the _previous_ (v1) documentation block is kept in the repo as well, even though it has much less material.
+
+We would recommend even Python users to just go through the JuliaCon2024 new block instead of the older version, due to its higher quality and numerous examples.

README.md

@@ -52,7 +52,7 @@ A video recording of the live version of this workshop, performed at the Max Pla
 
 ## Citing
 
-You can cite this material using the DOI 10.5281/zenodo.7789872  or the following BibTeX entry:
+You can cite this material using the DOI 10.5281/zenodo.7789872, or the following BibTeX entry:
 
 ```
 @software{goodscientificcode,
@@ -66,3 +66,4 @@ You can cite this material using the DOI 10.5281/zenodo.7789872  or the followin
   url          = {https://doi.org/10.5281/zenodo.7789872}
 }
 ```
+

block5_documentation/Documenter_GitHub_deploy.yaml

@@ -0,0 +1,45 @@
+name: Documentation
+# This is a standard Julia setup for GitHub CI
+on:
+  push:
+    branches:
+      - main # update to match your main branch
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+      pull-requests: read
+      statuses: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          version: '1'
+      - uses: julia-actions/cache@v1
+
+# Now this is where things focus on the documentation
+# build and deployment.
+
+# IMPORTANT! If your documentation is for a Julia package,
+# with formal Julia package structure (`src` folder and top level Project.toml)
+# then you need to include this extra step (simply uncomment it):
+
+      # - name: Develop local package
+      #   run: julia  'using Pkg; Pkg.develop(path="."); Pkg.instantiate()'
+
+# The next steps continue with the `doc` folder build.
+
+      # This is really all you care about; 2-steps process
+      # step 1, assumming the documentation Project.toml file is in `docs` folder
+      - name: Install docs dependencies
+        run: julia --project=docs/ 'using Pkg; Pkg.instantiate()'
+      # step 2 (note project path remains the same!)
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

block5_documentation/documentation_workshop_description.md

@@ -0,0 +1,15 @@
+This workshop is all about documentation. It's one of the most important aspects of code and software: it makes your code accessible to others, makes their experience with it pleasant, makes them wanna keep using it for the long run, and lowers the threshold for them to become contributors! Whether you are a maintainer of several registered Julia packages, or a just someone with an unregistered codebase that you believe can be useful for others, this workshop will be of use to you!
+
+The workshop will be fully hands-on, and will be composed by several iterations of [lecture -> application] for the covered topics. The main things it will cover are (among others, and depending on the real-time flow):
+
+1. Core principles of what makes a good documentation.
+1. The skeleton of a good documentation: exceptional, unambiguous docstrings.
+1. The different depths of exposition approach to documentation.
+1. The introductory tutorial.
+1. Layouting documentation pages.
+1. Tips & tricks for increasing clarity in the docs.
+1. Intro to Documenter.jl: key syntax and functions.
+1. Using Documenter.jl to generate runnable examples.
+1. Using Documenter.jl to deploy documentation online on a GitHub repository.
+1. Using DocumenterCitations.jl to cite literature robustly.
+1. Tips for reducing maintenance burden.