deploy: 52ece13

_sources/exercises.md.txt

@@ -0,0 +1,12 @@
+# List of exercises
+
+## Full list
+
+This is a list of all exercises and solutions in this lesson, mainly
+as a reference for helpers and instructors.  This list is
+automatically generated from all of the other pages in the lesson.
+Any single teaching event will probably cover only a subset of these,
+depending on their interests.
+
+```{exerciselist}
+```

_sources/gh-pages.md.txt

@@ -0,0 +1,62 @@
+(gh-pages)=
+
+# Hosting websites/homepages on GitHub Pages
+
+
+## Often we don't need more than a static website
+
+You can host your personal homepage or group webpage or project website on
+GitHub using [GitHub Pages](https://pages.github.com/).
+[GitLab](https://about.gitlab.com/features/pages/) and
+[Bitbucket](https://confluence.atlassian.com/bitbucket/publishing-a-website-on-bitbucket-cloud-221449776.html)
+also offer a very similar solution.
+
+Unless you need user authentication or a sophisticated database behind your
+website, [GitHub Pages](https://pages.github.com/) can be a very nice
+alternative to running your own web servers.  This is how all
+[https://coderefinery.org](https://coderefinery.org) material is hosted.
+
+
+## How to find the website URL
+
+Here below, NAMESPACE can either be a username or an organizational account.
+
+**Personal homepage or organizational homepage**
+- Generated URL: https://**NAMESPACE**.github.io
+- Generated from: https://github.com/**NAMESPACE**/**NAMESPACE**.github.io (main branch)
+
+**Project website**
+- Generated URL: https://**NAMESPACE**.github.io/**REPOSITORY**
+- Generated from: https://github.com/**NAMESPACE**/**REPOSITORY** (gh-pages branch)
+
+
+## Exercise - Your own website on GitHub Pages
+
+```{exercise} GH-Pages-2: Host your own github page
+- Deploy own website reusing a template:
+  - Follow the steps from GitHub Pages <https://pages.github.com/>.
+    The documentation there is very good so there is no need for us to duplicate the screenshots.
+  - Select "Project site".
+  - Select "Choose a theme".
+  - Follow the instructions on <https://pages.github.com/>.
+  - Browse your page on https://**USERNAME**.github.io/**REPOSITORY** (adjust "USERNAME" and "REPOSITORY").
+- Make a change to the repository after the webpage has been deployed for the first time.
+- Please wait few minutes and then verify that the change shows up on the website.
+```
+
+```{callout} Real-life examples
+- CodeRefinery website (built using [Zola](https://www.getzola.org/))
+  - [Source](https://raw.githubusercontent.com/coderefinery/coderefinery.org/main/content/lessons/core.md)
+  - Result: <https://coderefinery.org/lessons/core/>
+- This lesson (built using [Sphinx](https://www.sphinx-doc.org/)
+    and [MyST](https://myst-parser.readthedocs.io/)
+    and [sphinx-lesson](https://coderefinery.github.io/sphinx-lesson/))
+  - [Source](https://raw.githubusercontent.com/coderefinery/documentation/main/content/gh-pages.md)
+  - Result: this page
+```
+
+```{note}
+- You can use HTML directly or another static site generator if you prefer
+  to not use the default [Jekyll](https://jekyllrb.com/).
+- It is no problem to use a custom domain instead of `*.github.io`.
+```

_sources/gh_workflow.md.txt

@@ -0,0 +1,129 @@
+# Deploying Sphinx documentation to GitHub Pages
+
+```{objectives}
+- Create a basic workflow which you can take home and adapt for your project.
+```
+
+## [GitHub Pages](https://pages.github.com/)
+
+- Serve websites from a GitHub repository.
+- It is no problem to serve using your own URL `https://myproject.org` instead of `https://myuser.github.io/myproject`.
+
+
+## [GitHub Actions](https://github.com/features/actions/)
+
+- Automatically runs code when your repository changes.
+- We will let it run `sphinx-build` and make the result available to GitHub Pages.
+
+
+## Our goal: putting it all together
+
+- Host source code with documentation sources on a public Git repository.
+- Each time we `git push` to the repository, a GitHub action triggers to
+  rebuild the documentation.
+- The documentation is pushed to a separate branch called 'gh-pages'.
+
+---
+
+## Exercise - Deploy Sphinx documentation to GitHub Pages
+
+````{exercise} GH-Pages-1: Deploy Sphinx documentation to GitHub Pages
+In this exercise we will create an example repository on GitHub and
+deploy it to GitHub Pages.
+
+**Step 1**: Go to the [documentation-example](https://github.com/coderefinery/documentation-example/generate) project template
+on GitHub and create a copy to your namespace.
+- Give it a name, for instance "documentation-example".
+- You don't need to "Include all branches"
+- Click on "Create a repository".
+
+**Step 2**: Browse the new repository.
+- It will look very familar to the previous episode.
+- However, we have moved the documentation part under `doc/` (many projects do it this
+  way). But it is still a Sphinx documentation project.
+- The source code for your project could then go under `src/`.
+
+
+**Step 3**: Add the GitHub Action to your new Git repository.
+- Add a new file at `.github/workflows/documentation.yml` (either through terminal or web interface), containing:
+```yaml
+name: documentation
+
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser
+      - name: Sphinx build
+        run: |
+          sphinx-build doc _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true
+```
+- You don't need to understand all of the above, but you
+  might spot familiar commands in the `run:` sections.
+- After the file has been committed (and pushed),
+  check the action at `https://github.com/USER/documentation-example/actions`
+  (replace `USER` with your GitHub username).
+
+**Step 4**: Enable GitHub Pages
+- On GitHub go to "Settings" -> "Pages".
+- In the "Source" section, choose "Deploy from a branch" in the dropdown menu.
+- In the "Branch" section choose "gh-pages" and "/root" in the dropdown menus and click
+  save.
+- You should now be able to verify the pages deployment in the Actions list).
+
+**Step 5**: Verify the result
+- Your site should now be live on `https://USER.github.io/documentation-example/` (replace USER).
+
+**Step 6**: Verify refreshing the documentation
+- Commit some changes to your documentation
+- Verify that the documentation website refreshes after your changes (can take few seconds or a minute)
+````
+
+
+## Alternatives to GitHub Pages
+
+- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/)
+  and [GitLab CI](https://docs.gitlab.com/ee/ci/) can create a very similar workflow.
+
+- [Read the Docs](https://readthedocs.org) is the most common alternative to
+  hosting in GitHub Pages.
+
+- Sphinx builds HTML files (this is what static site generators do), and you
+  can host them anywhere, for example your university's web space or own web server.
+
+
+## Migrating your own documentation to Sphinx
+
+- First convert your documentation to Markdown using [Pandoc](https://pandoc.org).
+- Create a file `index.rst` which lists all other Markdown files and provides the
+  table of contents.
+- Add a `conf.py` file. You can generate a starting point for `conf.py` and
+  `index.rst` with `sphinx-quickstart`, or you can take the examples in this
+  lesson as inspiration.
+- Test building the documentation locally with `sphinx-build`.
+- Once this works, follow the above steps to build and deploy to GitHub Pages or some other web space.
+
+---
+
+```{keypoints}
+- Sphinx makes simple HTML (and more) files, so it is easy to find a place to host them.
+- Github Pages + Github Actions provides a convenient way to make
+  sites and host them on the web.
+```

_sources/guide.md.txt

@@ -0,0 +1,125 @@
+# Instructor guide
+
+
+## Why we teach this lesson
+
+Everyone should document their code, even if they're working alone.
+
+These are the main points:
+- Code documentation has to be versionnable and branchable
+- Code documentation should be tracked together with the source code
+- README is often enough
+
+**Please do not skim over the two above points**. Please take few minutes to
+explain why documentation (sources) should be tracked together with the source
+code.  Please discuss this aspect with workshop participants and connect it to
+**reproducibility**. This is for me (Radovan) the most important take-home
+message.
+
+Specific motivations:
+
+- Code documentation becomes quickly unmanageable if not part of the source code.
+- It helps people to quickly use your code thus reducing the time spent to explain over and again to new users.
+- It helps people to collaborate.
+- It improves the design of your code.
+
+
+## Intended learning outcomes
+
+By the end of this lesson, learners should:
+- Understand the importance of writing code documentation together with the source code
+- Know what makes a good documentation
+- Learn what tools can be used for writing documentation
+- Be able to motivate a balanced decision: sometimes READMEs are absolutely enough
+
+
+## Timing
+
+As an instructor you should prepare all bullet points but do not go through
+each bullet point in detail. Only highlight the main points and rather give
+time for a discussion. Leave details for a later lecture for those who want to
+find out more. If you go through each bullet point in detail, the motivation
+can easily take up 30 minutes and you will run out of time.
+
+The lesson does not fit into 1.5 hours if you go through everything. Optimize
+for discussions and prepare well to be able to jump over bullet points which
+can be left for a later lecture. Some sections can be skipped if needed (see
+below). However, we recommend to have a discussion with your learners to make
+them aware of what the training material contains.
+
+- Do not insist on practicing Markdown or RST syntax.
+- The section *Rendering (LaTeX) math equations* may be optional if your
+  attendees do not have to deal with equations.
+- In the GitHub Pages episode, the
+  goal is not anymore to write code documentation but to show how to build
+  project website with GitHub. If time is tight, the GitHub pages episode can be
+  skipped or can be done as demonstration instead of exercise.
+
+
+## Detailed schedule
+
+- 09:00 - 09:10 Motivation and tools
+  - create a wishlist in collaborative notes
+- 09:10 - 09:20 Writing good README files
+  - brief discussion
+- 09:20 - 09:40 **Exercises**: README-1, README-2, README-3 (choose one or multiple)
+- 09:40 - 10:00 Sphinx and Markdown: Sphinx-1 as type along
+
+- 10:00 - 10:10 Break
+
+- 10:10 - 10:40 **Exercises**, Sphinx-2, Sphinx-3, GH-Pages-1
+- 10:40 - 11:00 Discussion, GH Pages, Summary
+
+
+## Place this lesson towards the end of the workshop
+
+Reason is that with collaborative Git we can create more interesting
+documentation exercises. Currently there are some elements of forking and
+pushing and this is only really introduced on day two.  We have tried this
+lesson on day one and it felt too early and disconnected/abrupt.  It works best
+after the reproducibility lesson since we then reuse the example and it feels
+familiar.
+
+
+## Troubleshooting
+
+### Character encoding issues
+
+Can arise when using non-utf8 characters in `conf.py`. Diagnose this with `file -i conf.py`
+and `locale`.
+
+
+## Live better than reading the website material
+
+It is better to demonstrate the commands live and type-along. Ideally connecting
+to examples discussed earlier.
+
+In online workshops most of the type-along becomes group exercise work where groups
+can share screen and discuss.
+
+
+## Field reports
+
+### 2022 September
+
+We were pressed for time (we started 5-10 minutes late, relative to
+the schedule below), so we made most of the first lessons fast.  In
+the schedule below, note that we had the first 10 minutes for
+"Motivation" *and* "Popular tools", which we didn't fully realize so
+that put us even further behind.  Doing these introduction
+parts quickly was hard but was probably worth it since we had plenty
+of time in the end.  For the "tools", one person summarized the point
+of each section on the page quickly.  The README episode was done
+quickly, we basically skipped the exercises to get to Sphinx, and this
+put us back on schedule.
+
+For Sphinx, we did it a lot like you see in the schedule: first
+exercise (the basic setup) was type-along, but it was a bit too much
+to do in the 10 minutes we had allotted (we typed too fast).  But,
+people then had a nice long time to make it up and do everything.  It
+seemed to work well.  The GitHub pages deployment could then be done
+as a nice, slow demo, and we had plenty of time to ask questions.
+
+Overall, I think this was the right track, but we could have practiced
+doing the first parts even faster, and warned people that we focus on
+the Sphinx exercises.