Skip to content

Commit 7a8f0ad

Browse files
mmesitimmesiti
committed
deploy: cf51b52 
0 parents  commit 7a8f0ad

1,075 files changed

Lines changed: 157225 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.nojekyll‎

Whitespace-only changes.

‎_sources/exercises.md.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# List of exercises
2+
3+
## Full list
4+
5+
This is a list of all exercises and solutions in this lesson, mainly
6+
as a reference for helpers and instructors. This list is
7+
automatically generated from all of the other pages in the lesson.
8+
Any single teaching event will probably cover only a subset of these,
9+
depending on their interests.
10+
11+
```{exerciselist}
12+
```

‎_sources/gh-pages.md.txt‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
(gh-pages)=
2+
3+
# Hosting websites/homepages on GitHub Pages
4+
5+
6+
## Often we don't need more than a static website
7+
8+
You can host your personal homepage or group webpage or project website on
9+
GitHub using [GitHub Pages](https://pages.github.com/).
10+
[GitLab](https://about.gitlab.com/features/pages/) and
11+
[Bitbucket](https://confluence.atlassian.com/bitbucket/publishing-a-website-on-bitbucket-cloud-221449776.html)
12+
also offer a very similar solution.
13+
14+
Unless you need user authentication or a sophisticated database behind your
15+
website, [GitHub Pages](https://pages.github.com/) can be a very nice
16+
alternative to running your own web servers. This is how all
17+
[https://coderefinery.org](https://coderefinery.org) material is hosted.
18+
19+
20+
## How to find the website URL
21+
22+
Here below, NAMESPACE can either be a username or an organizational account.
23+
24+
**Personal homepage or organizational homepage**
25+
- Generated URL: https://**NAMESPACE**.github.io
26+
- Generated from: https://github.com/**NAMESPACE**/**NAMESPACE**.github.io (main branch)
27+
28+
**Project website**
29+
- Generated URL: https://**NAMESPACE**.github.io/**REPOSITORY**
30+
- Generated from: https://github.com/**NAMESPACE**/**REPOSITORY** (gh-pages branch)
31+
32+
33+
## Exercise - Your own website on GitHub Pages
34+
35+
```{exercise} GH-Pages-2: Host your own github page
36+
- Deploy own website reusing a template:
37+
- Follow the steps from GitHub Pages <https://pages.github.com/>.
38+
The documentation there is very good so there is no need for us to duplicate the screenshots.
39+
- Select "Project site".
40+
- Select "Choose a theme".
41+
- Follow the instructions on <https://pages.github.com/>.
42+
- Browse your page on https://**USERNAME**.github.io/**REPOSITORY** (adjust "USERNAME" and "REPOSITORY").
43+
- Make a change to the repository after the webpage has been deployed for the first time.
44+
- Please wait few minutes and then verify that the change shows up on the website.
45+
```
46+
47+
```{callout} Real-life examples
48+
- CodeRefinery website (built using [Zola](https://www.getzola.org/))
49+
- [Source](https://raw.githubusercontent.com/coderefinery/coderefinery.org/main/content/lessons/core.md)
50+
- Result: <https://coderefinery.org/lessons/core/>
51+
- This lesson (built using [Sphinx](https://www.sphinx-doc.org/)
52+
and [MyST](https://myst-parser.readthedocs.io/)
53+
and [sphinx-lesson](https://coderefinery.github.io/sphinx-lesson/))
54+
- [Source](https://raw.githubusercontent.com/coderefinery/documentation/main/content/gh-pages.md)
55+
- Result: this page
56+
```
57+
58+
```{note}
59+
- You can use HTML directly or another static site generator if you prefer
60+
to not use the default [Jekyll](https://jekyllrb.com/).
61+
- It is no problem to use a custom domain instead of `*.github.io`.
62+
```

‎_sources/gh_workflow.md.txt‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# Deploying Sphinx documentation to GitHub Pages
2+
3+
```{objectives}
4+
- Create a basic workflow which you can take home and adapt for your project.
5+
```
6+
7+
## [GitHub Pages](https://pages.github.com/)
8+
9+
- Serve websites from a GitHub repository.
10+
- It is no problem to serve using your own URL `https://myproject.org` instead of `https://myuser.github.io/myproject`.
11+
12+
13+
## [GitHub Actions](https://github.com/features/actions/)
14+
15+
- Automatically runs code when your repository changes.
16+
- We will let it run `sphinx-build` and make the result available to GitHub Pages.
17+
18+
19+
## Our goal: putting it all together
20+
21+
- Host source code with documentation sources on a public Git repository.
22+
- Each time we `git push` to the repository, a GitHub action triggers to
23+
rebuild the documentation.
24+
- The documentation is pushed to a separate branch called 'gh-pages'.
25+
26+
---
27+
28+
## Demonstration - Deploy Sphinx documentation to GitHub Pages
29+
30+
````{exercise} GH-Pages-1: Deploy Sphinx documentation to GitHub Pages
31+
In this exercise we will create an example repository on GitHub and
32+
deploy it to GitHub Pages.
33+
34+
**Step 1**: Go to the [documentation-example](https://github.com/coderefinery/documentation-example/generate) project template
35+
on GitHub and create a copy to your namespace.
36+
- Give it a name, for instance "documentation-example".
37+
- You don't need to "Include all branches"
38+
- Click on "Create a repository".
39+
40+
**Step 2**: Browse the new repository.
41+
- It will look very familar to the previous episode.
42+
- However, we have moved the documentation part under `doc/` (many projects do it this
43+
way). But it is still a Sphinx documentation project.
44+
- The source code for your project could then go under `src/`.
45+
46+
47+
**Step 3**: Add the GitHub Action to your new Git repository.
48+
- Add a new file at `.github/workflows/documentation.yml` (either through terminal or web interface), containing:
49+
```{code-block} yaml
50+
:linenos:
51+
:emphasize-lines: 16,19
52+
name: documentation
53+
54+
on: [push, pull_request, workflow_dispatch]
55+
56+
permissions:
57+
contents: write
58+
59+
jobs:
60+
docs:
61+
runs-on: ubuntu-latest
62+
steps:
63+
- uses: actions/checkout@v4
64+
- uses: actions/setup-python@v5
65+
- name: Install dependencies
66+
run: |
67+
pip install sphinx sphinx_rtd_theme myst_parser
68+
- name: Sphinx build
69+
run: |
70+
sphinx-build doc _build
71+
- name: Deploy to GitHub Pages
72+
uses: peaceiris/actions-gh-pages@v3
73+
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
74+
with:
75+
publish_branch: gh-pages
76+
github_token: ${{ secrets.GITHUB_TOKEN }}
77+
publish_dir: _build/
78+
force_orphan: true
79+
```
80+
- You don't need to understand all of the above
81+
-- you should mainly pay attention the highlighted lines
82+
which are shell commands (we know this because they are part of a `run: |` section).
83+
The first uses `pip` to install the dependencies and the second runs `sphinx-build`
84+
to actually build the documentation (as we saw in the previous episode).
85+
- After the file has been committed (and pushed),
86+
check the action at `https://github.com/USER/documentation-example/actions`
87+
(replace `USER` with your GitHub username).
88+
89+
**Step 4**: Enable GitHub Pages
90+
- On GitHub go to "Settings" -> "Pages".
91+
- Under "Build and deployment"
92+
- In the **Source** section: choose "Deploy from a branch" in the dropdown menu
93+
- In the **Branch** section: choose "gh-pages" and "/ (root)" in the dropdown menus
94+
and click the **Save** button.
95+
- You should now be able to verify the pages deployment in the "Actions" list
96+
([this is how it looks like](https://github.com/coderefinery/documentation/actions)
97+
for this lesson material).
98+
99+
**Step 5**: Verify the result
100+
- Your site should now be live on `https://USER.github.io/documentation-example/` (replace USER).
101+
102+
**Step 6 (optional)**: Verify refreshing the documentation
103+
- Commit some changes to your documentation
104+
- Verify that the documentation website refreshes after your changes (can take few seconds or a minute)
105+
````
106+
107+
## Exercise - Sphinx documentation on GitHub Pages
108+
````{exercise} GH-Pages-2: Putting it all together
109+
110+
1. Follow the above instructions to create a new repository with a Sphinx documentation project;
111+
2. Try adding one or more of the following to your Sphinx project:
112+
1. API documentation (see [previous exercise](#api-exercise) on API references) which requires the `sphinx-autodoc2` package.
113+
2. a Jupyter notebook (see [previous exercise](#jupyter-exercise) on Jupyter notebooks) which requires the `myst-nb` package.
114+
3. change the theme (see the end of [the quickstart](#quickstart)). You can browse themes and find their package names on the [Sphinx themes gallery](https://sphinx-themes.org/#themes).
115+
116+
```{important}
117+
The computer on which the GitHub actions run is *not* your local machine,
118+
and might not have the libraries you need to build the project.
119+
Make sure you update the dependencies (installed with `pip` in the demonstration) appropriately.
120+
```
121+
```{important}
122+
Make sure the correct file paths are used. This will require adjusting paths from the example from the previous episode to the new layout. Note many paths, including e.g. the `autodoc2_packages` preference are now relative to the `doc/` directory.
123+
```
124+
What do you need to change in the workflow file?
125+
126+
```{solution} Solution
127+
1. **API documentation**
128+
1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser sphinx-autodoc2`.
129+
2. Follow the instructions in [Sphinx-3](#api-exercise) changing paths so that:
130+
1. `multiply.py` is `src/multiply.py` and is specified as `../src/multiply.py` in the `autodoc2_packages` preference in `conf.py`
131+
2. `conf.py` is `doc/conf.py`
132+
3. `index.md` is `doc/index.md`.
133+
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.
134+
2. **a Jupyter notebook**
135+
1. Change line 16 of `.github/workflows/documentation.yml` from `pip install sphinx sphinx_rtd_theme myst_parser` to `pip install sphinx sphinx_rtd_theme myst_parser myst-nb`.
136+
2. Follow the instructions in [Sphinx-4](#jupyter-exercise) changing paths so that:
137+
1. `flower.md` is `docs/flower.md`
138+
2. `conf.py` is `doc/conf.py`
139+
3. `index.md` is `doc/index.md`.
140+
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.
141+
3. **change the theme**
142+
1. Change line 16 of `.github/workflows/documentation.yml` and add the theme package if necessary.
143+
2. In `docs/config.py` change `html_theme = 'sphinx_rtd_theme'` to the name of your chosen theme.
144+
3. Commit and push your changes, verify the action has run successfully, and view the built site in your browser.
145+
```
146+
````
147+
148+
## Alternatives to GitHub Pages
149+
150+
- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/)
151+
and [GitLab CI](https://docs.gitlab.com/ee/ci/) can create a very similar workflow.
152+
153+
- [Read the Docs](https://readthedocs.org) is the most common alternative to
154+
hosting in GitHub Pages.
155+
156+
- Sphinx builds HTML files (this is what static site generators do), and you
157+
can host them anywhere, for example your university's web space or own web server.
158+
159+
160+
## Migrating your own documentation to Sphinx
161+
162+
- First convert your documentation to Markdown using [Pandoc](https://pandoc.org).
163+
- Create a file `index.rst` which lists all other Markdown files and provides the
164+
table of contents.
165+
- Add a `conf.py` file. You can generate a starting point for `conf.py` and
166+
`index.rst` with `sphinx-quickstart`, or you can take the examples in this
167+
lesson as inspiration.
168+
- Test building the documentation locally with `sphinx-build`.
169+
- Once this works, follow the above steps to build and deploy to GitHub Pages or some other web space.
170+
171+
---
172+
173+
```{keypoints}
174+
- Sphinx makes simple HTML (and more) files, so it is easy to find a place to host them.
175+
- Github Pages + Github Actions provides a convenient way to make
176+
sites and host them on the web.
177+
```

‎_sources/guide.md.txt‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
# Instructor guide
2+
3+
4+
## Why we teach this lesson
5+
6+
Everyone should document their code, even if they're working alone.
7+
8+
These are the main points:
9+
- Code documentation has to be versionnable and branchable
10+
- Code documentation should be tracked together with the source code
11+
- README is often enough
12+
13+
**Please do not skim over the two above points**. Please take few minutes to
14+
explain why documentation (sources) should be tracked together with the source
15+
code. Please discuss this aspect with workshop participants and connect it to
16+
**reproducibility**. This is for me (Radovan) the most important take-home
17+
message.
18+
19+
Specific motivations:
20+
21+
- Code documentation becomes quickly unmanageable if not part of the source code.
22+
- It helps people to quickly use your code thus reducing the time spent to explain over and again to new users.
23+
- It helps people to collaborate.
24+
- It improves the design of your code.
25+
26+
27+
## Intended learning outcomes
28+
29+
By the end of this lesson, learners should:
30+
- Understand the importance of writing code documentation together with the source code
31+
- Know what makes a good documentation
32+
- Learn what tools can be used for writing documentation
33+
- Be able to motivate a balanced decision: sometimes READMEs are absolutely enough
34+
35+
36+
## Timing
37+
38+
As an instructor you should prepare all bullet points but do not go through
39+
each bullet point in detail. Only highlight the main points and rather give
40+
time for a discussion. Leave details for a later lecture for those who want to
41+
find out more. If you go through each bullet point in detail, the motivation
42+
can easily take up 30 minutes and you will run out of time.
43+
44+
The lesson does not fit into 1.5 hours if you go through everything. Optimize
45+
for discussions and prepare well to be able to jump over bullet points which
46+
can be left for a later lecture. Some sections can be skipped if needed (see
47+
below). However, we recommend to have a discussion with your learners to make
48+
them aware of what the training material contains.
49+
50+
- Do not insist on practicing Markdown or RST syntax.
51+
- The section *Rendering (LaTeX) math equations* may be optional if your
52+
attendees do not have to deal with equations.
53+
- In the GitHub Pages episode, the
54+
goal is not anymore to write code documentation but to show how to build
55+
project website with GitHub. If time is tight, the GitHub pages episode can be
56+
skipped or can be done as demonstration instead of exercise.
57+
58+
59+
## Detailed schedule
60+
61+
- 09:00 - 09:10 Motivation and tools
62+
- create a wishlist in collaborative notes
63+
- 09:10 - 09:20 Writing good README files
64+
- brief discussion
65+
- 09:20 - 09:40 **Exercises**: README-1, README-2, README-3 (choose one or multiple)
66+
- 09:40 - 10:00 Sphinx and Markdown: Sphinx-1 as type along
67+
68+
- 10:00 - 10:10 Break
69+
70+
- 10:10 - 10:40 **Exercises**, Sphinx-2, Sphinx-3, GH-Pages-1
71+
- 10:40 - 11:00 Discussion, GH Pages, Summary
72+
73+
74+
## Place this lesson towards the end of the workshop
75+
76+
Reason is that with collaborative Git we can create more interesting
77+
documentation exercises. Currently there are some elements of forking and
78+
pushing and this is only really introduced on day two. We have tried this
79+
lesson on day one and it felt too early and disconnected/abrupt. It works best
80+
after the reproducibility lesson since we then reuse the example and it feels
81+
familiar.
82+
83+
84+
## Troubleshooting
85+
86+
### Character encoding issues
87+
88+
Can arise when using non-utf8 characters in `conf.py`. Diagnose this with `file -i conf.py`
89+
and `locale`.
90+
91+
92+
## Live better than reading the website material
93+
94+
It is better to demonstrate the commands live and type-along. Ideally connecting
95+
to examples discussed earlier.
96+
97+
In online workshops most of the type-along becomes group exercise work where groups
98+
can share screen and discuss.
99+
100+
101+
## Field reports
102+
103+
### 2022 September
104+
105+
We were pressed for time (we started 5-10 minutes late, relative to
106+
the schedule below), so we made most of the first lessons fast. In
107+
the schedule below, note that we had the first 10 minutes for
108+
"Motivation" *and* "Popular tools", which we didn't fully realize so
109+
that put us even further behind. Doing these introduction
110+
parts quickly was hard but was probably worth it since we had plenty
111+
of time in the end. For the "tools", one person summarized the point
112+
of each section on the page quickly. The README episode was done
113+
quickly, we basically skipped the exercises to get to Sphinx, and this
114+
put us back on schedule.
115+
116+
For Sphinx, we did it a lot like you see in the schedule: first
117+
exercise (the basic setup) was type-along, but it was a bit too much
118+
to do in the 10 minutes we had allotted (we typed too fast). But,
119+
people then had a nice long time to make it up and do everything. It
120+
seemed to work well. The GitHub pages deployment could then be done
121+
as a nice, slow demo, and we had plenty of time to ask questions.
122+
123+
Overall, I think this was the right track, but we could have practiced
124+
doing the first parts even faster, and warned people that we focus on
125+
the Sphinx exercises.

0 commit comments

Comments
 (0)