deploy: fa40923

.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,67 @@
+(gh-pages)=
+
+# Hosting websites/homepages on GitHub Pages
+
+```{questions}
+- How to serve a website/homepage using GitHub
+```
+
+## Hosting websites/homepages on GitHub Pages
+
+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.
+
+---
+
+```{figure} img/gh-pages.svg
+:alt: Scheme that describes how branch names end up websites
+
+Scheme that describes how branch names end up websites.
+```
+
+---
+
+## Exercise - Your own github page
+
+```{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" (for instance "Minimal")
+  - Click "Select theme"
+  - Adjust the README.md and commit
+  - Browse your page on `http://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
+- Research Software Hour (built using [Zola](https://www.getzola.org/))
+  - [Source](https://raw.githubusercontent.com/ResearchSoftwareHour/researchsoftwarehour.github.io/main/content/about.md)
+  - Result: <https://researchsoftwarehour.github.io/about/>
+- 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,170 @@
+# 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 run Sphinx build and make the result available to GitHub Pages
+- Equations and images no problem
+- Can use Sphinx styles
+
+## Typical workflow
+
+- Host source code with documentation sources on a public Git repository.
+- Each time you `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. The example project contains a script for
+counting the frequency distribution of words in a given file and some
+documentation generated using Sphinx. For bigger projects, we can have
+more source files.
+
+**Step 1:** Go to the [documentation-example project template](https://github.com/coderefinery/documentation-example/generate)
+on GitHub and create a copy to your namespace ("Generate", since this
+is a template repository).
+
+**Clone the repository**
+
+The repository contains following two folders, among few other files:
+- **source** folder contains the source code
+- **doc** folder contains the Sphinx documentation
+
+The doc folder contains the Sphinx configuration file (`conf.py`) and the index file (`index.rst`) and some contents (Markdown files).
+The `conf.py` file has been adjusted to be able to autogenerate documentation from sources.
+
+
+**Build HTML pages locally**
+
+Inside the cloned repository, build the documentation and verify the result in your browser:
+
+```console
+$ sphinx-build doc _build
+```
+
+**Test HTML pages links**
+
+Inside the cloned repository, check the integrity of all internal and external links:
+
+```console
+$ sphinx-build doc -W -b linkcheck -d _build/doctrees _build/html
+```
+
+**Step 2:** Add the GitHub Action
+
+- Create a new file at `.github/workflows/documentation.yaml` with the contents
+
+```yaml
+name: Docs
+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
+      - name: Sphinx build
+        run: |
+          sphinx-build doc _build
+      - name: Deploy
+        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.
+
+- Add, commit and push to GitHub
+- Check the action at `https://github.com/<myuser>/documentation-example/actions`.
+Replace `<myuser>` with your GitHub username.
+
+**Step 2:** Enable GitHub Pages
+
+- Go to `https://github.com/<myuser>/documentation-example/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 be able to verify the pages deployment in the Actions list)
+
+
+**Verify the result**
+
+That's it! Your site should now be live on
+`https://<myuser>.github.io/documentation-example/` (replace username).
+
+**Verify refreshing the documentation**
+
+Finally, make some changes to your documentation
+- Add documentation related to other functions
+- Prerequisites and how to use the program
+- Rules for contribution
+- Some example results (figures, tables, ...)
+- Commit and push them, and verify that the documentation website refreshes after your changes (can take few seconds or a minute)
+``````
+
+```{callout} Do not add the generated build directory to your repository
+The `_build` directory is generated locally with the command `sphinx-build
+doc _build` and allows you to check the content locally but it should not be
+part of the Git repository.  We recommend to add `_build` to `.gitignore` to
+prevent you from accidentally adding files below `_build` to the Git
+repository.
+```
+
+
+## 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 simply builds HTML files, and you can host them anywhere, for
+example your university's web space or own web server.  This is the
+whole point of **static site generators**.
+
+
+## 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 RST 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.
+
+
+
+---
+
+```{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.
+```