deploy: bc1ce02

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: b4eea5dbac7457e85cc7048b631142d0
+tags: d77d1c0d9ca2f4c8421862c7c5a0d620

_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 `http://myproject.org` instead of `http://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@v3
+      - uses: actions/setup-python@v3
+      - 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 form 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.
+```