Skip to content

Commit

Permalink
Merge branch 'main' into rkdarst/ssh-or-https
Browse files Browse the repository at this point in the history
  • Loading branch information
@bast
bast authored Sep 14, 2023
2 parents f02c913 + d348cfd commit 7b3945c
Show file tree
Hide file tree
Showing 9 changed files with 167 additions and 125 deletions.
182 changes: 110 additions & 72 deletions .github/workflows/sphinx.yml
View file
Original file line number Diff line number Diff line change
@@ -1,120 +1,158 @@
# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml
# Deploy Sphinx. This could be shorter, but we also do some extra
# stuff.
#
# License: CC-0. This is the canonical location of this file, which
# you may want to link to anyway:
# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml


name: sphinx
on: [push, pull_request]

# If these SPHINXOPTS are enabled, then be strict about the builds and
# fail on any warnings
#env:
# SPHINXOPTS: "-W --keep-going -T"
env:
DEFAULT_BRANCH: "main"
# If these SPHINXOPTS are enabled, then be strict about the
# builds and fail on any warnings.
#SPHINXOPTS: "-W --keep-going -T"
GENERATE_PDF: true # to enable, must be 'true' lowercase
PDF_FILENAME: lesson.pdf
MULTIBRANCH: true # to enable, must be 'true' lowercase


jobs:
build-and-deploy:
name: Build and gh-pages
build:
name: Build
runs-on: ubuntu-latest
permissions:
contents: read

steps:
# https://github.com/marketplace/actions/checkout
- uses: actions/checkout@v2
- uses: actions/checkout@v4
with:
fetch-depth: 0
lfs: true

# https://github.com/marketplace/actions/setup-python
# ^-- This gives info on matrix testing.
- name: Install Python
uses: actions/setup-python@v2
with:
python-version: 3.8
# https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
# ^-- How to set up caching for pip on Ubuntu
- name: Cache pip
uses: actions/cache@v2
uses: actions/setup-python@v4
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
restore-keys: |
${{ runner.os }}-pip-
${{ runner.os }}-
python-version: '3.11'
cache: 'pip'

# https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
# ^-- This gives info on installing dependencies with pip
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install -r requirements.txt
# Debug
- name: Debugging information
env:
ref: ${{github.ref}}
event_name: ${{github.event_name}}
head_ref: ${{github.head_ref}}
base_ref: ${{github.base_ref}}
run: |
echo "github.ref:" ${{github.ref}}
echo "github.event_name:" ${{github.event_name}}
echo "github.head_ref:" ${{github.head_ref}}
echo "github.base_ref:" ${{github.base_ref}}
echo "github.ref: ${ref}"
echo "github.event_name: ${event_name}"
echo "github.head_ref: ${head_ref}"
echo "github.base_ref: ${base_ref}"
echo "GENERATE_PDF: ${GENERATE_PDF}"
set -x
git rev-parse --abbrev-ref HEAD
git branch
git branch -a
git remote -v
python -V
pip list --not-required
pip list
# Build
- uses: ammaraskar/sphinx-problem-matcher@master
- name: Build Sphinx docs
- name: Build Sphinx docs (dirhtml)
# SPHINXOPTS used via environment variables
run: |
make dirhtml
# This fixes broken copy button icons, as explained in
# https://github.com/coderefinery/sphinx-lesson/issues/50
# https://github.com/executablebooks/sphinx-copybutton/issues/110
# This can be removed once these PRs are accepted (but the
# fixes also need to propagate to other themes):
# https://github.com/sphinx-doc/sphinx/pull/8524
# https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
# PDF if requested
- name: Generate PDF
if: ${{ env.GENERATE_PDF == 'true' }}
run: |
pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
make pyppeteer
mv _build/pyppeteer/*.pdf _build/dirhtml/_static/${PDF_FILENAME}.pdf
# The following supports building all branches and combining on
# gh-pages

# Clone and set up the old gh-pages branch
- name: Clone old gh-pages
# Stage all deployed assets in _gh-pages/ for simplicity, and to
# prepare to do a multi-branch deployment.
- name: Copy deployment data to _gh-pages/
if: ${{ github.event_name == 'push' }}
run: |
set -x
git fetch
( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
rm -rf _gh-pages/.git/
mkdir -p _gh-pages/branch/
# If a push and main, copy build to _gh-pages/ as the "main"
# deployment.
- name: Copy new build (main)
if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
run: |
set -x
# Delete everything under _gh-pages/ that is from the
# primary branch deployment. Eicludes the other branches
# _gh-pages/branch-* paths, and not including
# _gh-pages itself.
find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
run:
rsync -a _build/dirhtml/ _gh-pages/
# If a push and not on main, then copy the build to
# _gh-pages/branch/$brname (transforming '/' into '--')
- name: Copy new build (branch)
if: ${{ github.event_name == 'push' && github.ref != 'refs/heads/main' }}
run: |
set -x
#brname=$(git rev-parse --abbrev-ref HEAD)
brname="${{github.ref}}"
brname="${brname##refs/heads/}"
brdir=${brname//\//--} # replace '/' with '--'
rm -rf _gh-pages/branch/${brdir}
rsync -a _build/dirhtml/ _gh-pages/branch/${brdir}
# Go through each branch in _gh-pages/branch/, if it's not a
# ref, then delete it.
- name: Delete old feature branches

# Use gh-pages-multibranch to multiplex different branches into
# one deployment. See
# https://github.com/coderefinery/gh-pages-multibranch
- name: gh-pages multibranch
uses: coderefinery/gh-pages-multibranch@main
if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
with:
directory: _gh-pages/
default_branch: ${{ env.DEFAULT_BRANCH }}
publish_branch: gh-pages

# Add the .nojekyll file
- name: nojekyll
if: ${{ github.event_name == 'push' }}
run: |
set -x
for brdir in `ls _gh-pages/branch/` ; do
brname=${brdir//--/\/} # replace '--' with '/'
if ! git show-ref remotes/origin/$brname ; then
echo "Removing $brdir"
rm -r _gh-pages/branch/$brdir/
fi
done
touch _gh-pages/.nojekyll
# Save artifact for the next step.
- uses: actions/upload-artifact@master
if: ${{ github.event_name == 'push' }}
with:
name: gh-pages-build
path: _gh-pages/

# Deploy in a separate job so that write permissions are restricted
# to the minimum steps.
deploy:
name: Deploy
runs-on: ubuntu-latest
needs: build
# This if can't use the env context - find better way later.
if: ${{ github.event_name == 'push' }}
permissions:
contents: write

steps:
- uses: actions/download-artifact@v3
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
with:
name: gh-pages-build
path: _gh-pages/

# As of 2023, we could publish to pages via a Deployment. This
# isn't done yet to give it time to stabilize (out of beta), and
# also having a gh-pages branch to check out is rather
# convenient.

# Deploy
# https://github.com/peaceiris/actions-gh-pages
- name: Deploy
uses: peaceiris/actions-gh-pages@v3
if: ${{ github.event_name == 'push' }}
#if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/main' }}
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
with:
publish_branch: gh-pages
github_token: ${{ secrets.GITHUB_TOKEN }}
Expand Down
16 changes: 8 additions & 8 deletions content/archaeology.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ With `git grep` you can find all lines in a repository which contain some string
This is useful to find out where in the code some variable is used or some error message printed:

```console
$ git grep sometext
$ git grep TEXT
$ git grep "some text with spaces"
```

Expand All @@ -78,7 +78,7 @@ We have seen this one before already. Using `git show` we can inspect an individ
we know its hash:

```console
$ git show somehash
$ git show HASH
```

For instance:
Expand All @@ -95,7 +95,7 @@ last. It also prints the precise hash of the last change which modified each lin
for reproducibility.

```console
$ git annotate somefile
$ git annotate FILE
```

Example:
Expand All @@ -122,7 +122,7 @@ We can create branches pointing to a commit in the past.
This is the recommended mechanism to inspect old code:

```console
$ git switch --create branchname somehash
$ git switch --create BRANCHNAME HASH
```

Example (lines starting with "#" are only comments):
Expand Down Expand Up @@ -249,7 +249,7 @@ We will probably arrive at a solution which is similar to `git bisect`:
```
- Then bisect/iterate your way until you find the commit that broke it.
- If you want to go back to start, type `git bisect reset`.
- This can even be automatized with `git bisect run <script>`.
- This can even be automatized with `git bisect run SCRIPT`.
For this you write a script that returns zero/non-zero (success/failure).

(exercise-bisect)=
Expand Down Expand Up @@ -308,17 +308,17 @@ We will probably arrive at a solution which is similar to `git bisect`:

How to navigate to the parent of a commit with hash `somehash`:
```console
$ git switch --create branchname somehash~1
$ git switch --create BRANCHNAME SOMEHASH~1
```

Instead of a tilde you can also use this:
```console
$ git switch --create branchname somehash^
$ git switch --create BRANCHNAME SOMEHASH^
```
````

```{keypoints}
- git log/grep/annotate/show/bisect is a powerful combination when doing archaeology in a project.
- `git switch --create <name> <hash>` is the recommended mechanism to inspect old code.
- `git switch --create NAME HASH` is the recommended mechanism to inspect old code.
- On newer Git you can use the more intuitive `git switch --create branchname somehash`.
```
14 changes: 7 additions & 7 deletions content/basics.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,10 +31,10 @@
- Example (we don't need to type yet):

```console
$ git add somefile.txt
$ git add FILE.txt
$ git commit

$ git add file.txt anotherfile.txt
$ git add FILE.txt ANOTHERFILE.txt
$ git commit
```

Expand Down Expand Up @@ -314,21 +314,21 @@ Date: Wed Feb 9 10:11:30 2022 +0100
## Optional exercises: comparing, renaming, and removing

```{exercise} (optional) Basic-2: Comparing and showing commits
1. Inspect differences between commit hashes with `git diff <hash1> <hash2>`.
2. Have a look at specific commits with `git show <hash>`.
1. Inspect differences between commit hashes with `git diff HASH1 HASH2`.
2. Have a look at specific commits with `git show HASH`.
```

````{exercise} (optional) Basic-3: Visual diff tools
- Make further modifications and experiment with `git difftool` (requires installing one of the [visual diff tools](https://coderefinery.github.io/installation/difftools/)):
On Windows or Linux:
```console
$ git difftool --tool=meld <hash>
$ git difftool --tool=meld HASH
```
On macOS:
```console
$ git difftool --tool=opendiff <hash>
$ git difftool --tool=opendiff HASH
```
```{figure} img/meld.png
Expand Down Expand Up @@ -478,7 +478,7 @@ But it is also possible to work from within a Git graphical user interface (GUI)
Now we know how to save snapshots:

```console
$ git add <file(s)>
$ git add FILE(S)
$ git commit
```

Expand Down
20 changes: 11 additions & 9 deletions content/branches.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,9 @@ Linear Git repository.

- Commits are depicted here as little boxes with abbreviated hashes.
- Here the branch `main` points to a commit.
- "HEAD" is the current position (remember the recording head of tape recorders?).
- "HEAD" is the current position (remember the recording head of tape
recorders?). (when we say `HEAD`, we mean those literal letters -
this isn't a placeholder for something else)
- When we talk about branches, we often mean all parent commits, not only the commit pointed to.


Expand Down Expand Up @@ -549,24 +551,24 @@ Let us pause for a moment and recapitulate what we have just learned:

```console
$ git branch # see where we are
$ git branch <name> # create branch <name>
$ git switch <name> # switch to branch <name>
$ git merge <name> # merge branch <name> (to current branch)
$ git branch -d <name> # delete branch <name>
$ git branch -D <name> # delete unmerged branch
$ git branch NAME # create branch NAME
$ git switch NAME # switch to branch NAME
$ git merge NAME # merge branch NAME (to current branch)
$ git branch -d NAME # delete branch NAME
$ git branch -D NAME # delete unmerged branch
```

Since the following command combo is so frequent:

```console
$ git branch <name> # create branch <name>
$ git switch <name> # switch to branch <name>
$ git branch NAME # create branch NAME
$ git switch NAME # switch to branch NAME
```

There is a shortcut for it:

```console
$ git switch --create <name> # create branch <name> and switch to it
$ git switch --create NAME # create branch NAME and switch to it
```

### Typical workflows
Expand Down
Loading

0 comments on commit 7b3945c

Please sign in to comment.