Skip to content

Commit de08c70

Browse files
samumanthasamumantha
authored
Merge branch 'main' into citation
2 parents 06b3051 + 7ec7d22 commit de08c70

File tree

9 files changed

+449
-253
lines changed

9 files changed

+449
-253
lines changed

‎.github/workflows/sphinx.yml‎

Lines changed: 101 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,51 +1,69 @@
1-
# From: https://github.com/rkdarst/sphinx-actions-test/blob/master/.github/workflows/sphinx-build.yml
1+
# Deploy Sphinx. This could be shorter, but we also do some extra
2+
# stuff.
3+
#
4+
# License: CC-0. This is the canonical location of this file, which
5+
# you may want to link to anyway:
6+
# https://github.com/coderefinery/sphinx-lesson-template/blob/main/.github/workflows/sphinx.yml
7+
# https://raw.githubusercontent.com/coderefinery/sphinx-lesson-template/main/.github/workflows/sphinx.yml
8+
29

310
name: sphinx
411
on: [push, pull_request]
512

613
env:
714
DEFAULT_BRANCH: "main"
15+
# If these SPHINXOPTS are enabled, then be strict about the
16+
# builds and fail on any warnings.
817
#SPHINXOPTS: "-W --keep-going -T"
9-
# ^-- If these SPHINXOPTS are enabled, then be strict about the builds and fail on any warnings
18+
GENERATE_PDF: true # to enable, must be 'true' lowercase
19+
GENERATE_SINGLEHTML: true # to enable, must be 'true' lowercase
20+
PDF_FILENAME: lesson.pdf
21+
MULTIBRANCH: true # to enable, must be 'true' lowercase
22+
1023

1124
jobs:
12-
build-and-deploy:
13-
name: Build and gh-pages
25+
build:
26+
name: Build
1427
runs-on: ubuntu-latest
28+
permissions:
29+
contents: read
30+
1531
steps:
1632
# https://github.com/marketplace/actions/checkout
17-
- uses: actions/checkout@v2
33+
- uses: actions/checkout@v4
1834
with:
1935
fetch-depth: 0
2036
lfs: true
37+
2138
# https://github.com/marketplace/actions/setup-python
2239
# ^-- This gives info on matrix testing.
2340
- name: Install Python
24-
uses: actions/setup-python@v2
41+
uses: actions/setup-python@v4
2542
with:
26-
python-version: 3.8
27-
# https://docs.github.com/en/actions/guides/building-and-testing-python#caching-dependencies
28-
# ^-- How to set up caching for pip on Ubuntu
29-
- name: Cache pip
30-
uses: actions/cache@v2
31-
with:
32-
path: ~/.cache/pip
33-
key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
34-
restore-keys: |
35-
${{ runner.os }}-pip-
36-
${{ runner.os }}-
43+
python-version: '3.11'
44+
cache: 'pip'
45+
3746
# https://docs.github.com/en/actions/guides/building-and-testing-python#installing-dependencies
3847
# ^-- This gives info on installing dependencies with pip
3948
- name: Install dependencies
4049
run: |
4150
python -m pip install --upgrade pip
4251
pip install -r requirements.txt
52+
53+
# Debug
4354
- name: Debugging information
55+
env:
56+
ref: ${{github.ref}}
57+
event_name: ${{github.event_name}}
58+
head_ref: ${{github.head_ref}}
59+
base_ref: ${{github.base_ref}}
4460
run: |
45-
echo "github.ref:" ${{github.ref}}
46-
echo "github.event_name:" ${{github.event_name}}
47-
echo "github.head_ref:" ${{github.head_ref}}
48-
echo "github.base_ref:" ${{github.base_ref}}
61+
echo "github.ref: ${ref}"
62+
echo "github.event_name: ${event_name}"
63+
echo "github.head_ref: ${head_ref}"
64+
echo "github.base_ref: ${base_ref}"
65+
echo "GENERATE_PDF: ${GENERATE_PDF}"
66+
echo "GENERATE_SINGLEHTML: ${GENERATE_SINGLEHTML}"
4967
set -x
5068
git rev-parse --abbrev-ref HEAD
5169
git branch
@@ -54,11 +72,12 @@ jobs:
5472
python -V
5573
pip list --not-required
5674
pip list
57-
75+
5876
5977
# Build
6078
- uses: ammaraskar/sphinx-problem-matcher@master
61-
- name: Build Sphinx docs
79+
- name: Build Sphinx docs (dirhtml)
80+
# SPHINXOPTS used via environment variables
6281
run: |
6382
make dirhtml
6483
# This fixes broken copy button icons, as explained in
@@ -70,73 +89,80 @@ jobs:
7089
# https://github.com/readthedocs/sphinx_rtd_theme/pull/1025
7190
sed -i 's/url_root="#"/url_root=""/' _build/dirhtml/index.html || true
7291
92+
# singlehtml
93+
- name: Generate singlehtml
94+
if: ${{ env.GENERATE_SINGLEHTML == 'true' }}
95+
run: |
96+
make singlehtml
97+
mv _build/singlehtml/ _build/dirhtml/singlehtml/
7398
74-
# The following supports building all branches and combining on
75-
# gh-pages
99+
# PDF if requested
100+
- name: Generate PDF
101+
if: ${{ env.GENERATE_PDF == 'true' }}
102+
run: |
103+
pip install https://github.com/rkdarst/sphinx_pyppeteer_builder/archive/refs/heads/main.zip
104+
make pyppeteer
105+
mv _build/pyppeteer/*.pdf _build/dirhtml/${PDF_FILENAME}
76106
77-
# Clone and set up the old gh-pages branch
78-
- name: Clone old gh-pages
107+
# Stage all deployed assets in _gh-pages/ for simplicity, and to
108+
# prepare to do a multi-branch deployment.
109+
- name: Copy deployment data to _gh-pages/
79110
if: ${{ github.event_name == 'push' }}
80-
run: |
81-
set -x
82-
git fetch
83-
( git branch gh-pages remotes/origin/gh-pages && git clone . --branch=gh-pages _gh-pages/ ) || mkdir _gh-pages
84-
rm -rf _gh-pages/.git/
85-
mkdir -p _gh-pages/branch/
86-
# If a push and default branch, copy build to _gh-pages/ as the "main"
87-
# deployment.
88-
- name: Copy new build (default branch)
89-
if: |
90-
contains(github.event_name, 'push') &&
91-
contains(github.ref, env.DEFAULT_BRANCH)
92-
run: |
93-
set -x
94-
# Delete everything under _gh-pages/ that is from the
95-
# primary branch deployment. Eicludes the other branches
96-
# _gh-pages/branch-* paths, and not including
97-
# _gh-pages itself.
98-
find _gh-pages/ -mindepth 1 ! -path '_gh-pages/branch*' -delete
111+
run:
99112
rsync -a _build/dirhtml/ _gh-pages/
100-
# If a push and not on default branch, then copy the build to
101-
# _gh-pages/branch/$brname (transforming '/' into '--')
102-
- name: Copy new build (branch)
103-
if: |
104-
contains(github.event_name, 'push') &&
105-
!contains(github.ref, env.DEFAULT_BRANCH)
106-
run: |
107-
set -x
108-
#brname=$(git rev-parse --abbrev-ref HEAD)
109-
brname="${{github.ref}}"
110-
brname="${brname##refs/heads/}"
111-
brdir=${brname//\//--} # replace '/' with '--'
112-
rm -rf _gh-pages/branch/${brdir}
113-
rsync -a _build/dirhtml/ _gh-pages/branch/${brdir}
114-
# Go through each branch in _gh-pages/branch/, if it's not a
115-
# ref, then delete it.
116-
- name: Delete old feature branches
117-
if: ${{ github.event_name == 'push' }}
118-
run: |
119-
set -x
120-
for brdir in `ls _gh-pages/branch/` ; do
121-
brname=${brdir//--/\/} # replace '--' with '/'
122-
if ! git show-ref remotes/origin/$brname ; then
123-
echo "Removing $brdir"
124-
rm -r _gh-pages/branch/$brdir/
125-
fi
126-
done
113+
114+
# Use gh-pages-multibranch to multiplex different branches into
115+
# one deployment. See
116+
# https://github.com/coderefinery/gh-pages-multibranch
117+
- name: gh-pages multibranch
118+
uses: coderefinery/gh-pages-multibranch@main
119+
if: ${{ github.event_name == 'push' && env.MULTIBRANCH == 'true' }}
120+
with:
121+
directory: _gh-pages/
122+
default_branch: ${{ env.DEFAULT_BRANCH }}
123+
publish_branch: gh-pages
127124

128125
# Add the .nojekyll file
129126
- name: nojekyll
130127
if: ${{ github.event_name == 'push' }}
131128
run: |
132129
touch _gh-pages/.nojekyll
133130
131+
# Save artifact for the next step.
132+
- uses: actions/upload-artifact@v4
133+
if: ${{ github.event_name == 'push' }}
134+
with:
135+
name: gh-pages-build
136+
path: _gh-pages/
137+
138+
# Deploy in a separate job so that write permissions are restricted
139+
# to the minimum steps.
140+
deploy:
141+
name: Deploy
142+
runs-on: ubuntu-latest
143+
needs: build
144+
# This if can't use the env context - find better way later.
145+
if: ${{ github.event_name == 'push' }}
146+
permissions:
147+
contents: write
148+
149+
steps:
150+
- uses: actions/download-artifact@v4
151+
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
152+
with:
153+
name: gh-pages-build
154+
path: _gh-pages/
155+
156+
# As of 2023, we could publish to pages via a Deployment. This
157+
# isn't done yet to give it time to stabilize (out of beta), and
158+
# also having a gh-pages branch to check out is rather
159+
# convenient.
160+
134161
# Deploy
135162
# https://github.com/peaceiris/actions-gh-pages
136163
- name: Deploy
137164
uses: peaceiris/actions-gh-pages@v3
138-
if: ${{ github.event_name == 'push' }}
139-
#if: ${{ success() && github.event_name == 'push' && github.ref == 'refs/heads/$defaultBranch' }}
165+
if: ${{ github.event_name == 'push' && ( env.MULTIBRANCH == 'true' || github.ref == format('refs/heads/{0}', env.DEFAULT_BRANCH )) }}
140166
with:
141167
publish_branch: gh-pages
142168
github_token: ${{ secrets.GITHUB_TOKEN }}

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Lesson: social coding
1+
# Social coding and open software - What can you do to get credit for your code and to allow reuse
22

33
- Text: free to share and remix under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
44

‎content/conf.py‎

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,10 @@
1717

1818
# -- Project information -----------------------------------------------------
1919

20-
project = "Social coding"
20+
project = "Social coding and open software"
2121
copyright = "CodeRefinery contributors"
2222
author = "CodeRefinery contributors"
23+
2324
github_user = "coderefinery"
2425
github_repo_name = "social-coding" # auto-detected from dirname if blank
2526
github_version = "main"
@@ -46,12 +47,7 @@
4647
"sphinx_coderefinery_branding",
4748
]
4849

49-
# Settings for myst_nb:
50-
# https://myst-nb.readthedocs.io/en/latest/use/execute.html#triggering-notebook-execution
51-
# jupyter_execute_notebooks = "off"
52-
# jupyter_execute_notebooks = "auto" # *only* execute if at least one output is missing.
53-
# jupyter_execute_notebooks = "force"
54-
jupyter_execute_notebooks = "cache"
50+
nb_execution_mode = "cache"
5551

5652
# Add any paths that contain templates here, relative to this directory.
5753
# templates_path = ['_templates']

‎content/guide.md‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -10,24 +10,24 @@ There are the following main acts:
1010
- First section is about social coding and sharing code and motivation for
1111
sharing code with a discussion that licensing alone isn't enough. If you want
1212
people to use your work, you need to do more to make your work easily reusable.
13-
Use this as an entry point to tell people what is coming up in the rest of
14-
CodeRefinery (if this talk is on day 1 of a CodeRefinery workshop) or
15-
re-emphasize how past lessons all fit together (if on the last day).
1613

1714
- Emphasis of the concept of derivative work and that everything is
18-
based on other things. And if your goal is citations, you want as
19-
many people using your work as possible, because then they can cite
20-
you.
15+
based on other things. And if your goal is citations, you want as many
16+
people using your work as possible, because then they can cite you.
2117

2218
- Overview of license types. There are many
23-
online resources, and the biggest
24-
question is permissive vs. weak copyleft vs. strong copyleft. The [cake analogy
25-
for licenses](https://cicero.xyz/v3/remark/0.14.0/github.com/coderefinery/social-coding/main/licensing-and-cakes.md/) is only linked
26-
and can be skipped and does not have to be discussed in detail.
19+
online resources, and the biggest question is permissive vs. weak copyleft
20+
vs. strong copyleft.
21+
The [cake analogy for licenses](https://cicero.xyz/v3/remark/0.14.0/github.com/coderefinery/social-coding/main/licensing-and-cakes.md/)
22+
is only linked and can be skipped and does not have to be discussed in
23+
detail.
2724

28-
- Finally a brief section on code citations. It's good if you manage to start a discussion
25+
- Then a brief section on code citations. It's good if you manage to start a discussion
2926
around this topic.
3027

28+
- The "Sharing data" part is meant to bring awareness about FAIRness and
29+
Open Science and to show how DOIs can be obtained for Git repositories.
30+
3131

3232
## Hints
3333

‎content/index.rst‎

Lines changed: 31 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,35 @@
1-
Social coding
2-
=============
1+
Social coding and open software - What can you do to get credit for your code and to allow reuse
2+
================================================================================================
33

4-
In this lesson we will discuss how and why to share code, what kind of licenses
5-
are used in what situation, and how software can be cited.
4+
In this lesson we will discuss how and why to share code and data, what kind of
5+
licenses are used in what situation, and how software can be cited.
66

77
We will try to connect software licenses to FAIR principles, give practical
88
recommendations for starting, contributing, and reusing code and help you
99
navigating and deciding on licenses.
1010

1111

12+
.. admonition:: Why software licenses matter
13+
14+
- You **find some great code** or data that you want to reuse for your own
15+
publication (good for the original author: you will cite them and maybe other
16+
people who cite you will cite them).
17+
18+
- You need to **modify the code** a little bit, or you remix the data a bit.
19+
20+
- When it comes time to publish, you realize there is no **license**.
21+
22+
Now we have a problem:
23+
24+
- You manage to **publish the paper without the software/data** but others cannot
25+
build on your software and data and
26+
you don't get as many citations as you could.
27+
- Or, you **cannot publish it at all** if the journal requires that papers should
28+
come with data and software so that they are reproducible.
29+
30+
This lesson is about how to avoid this situation for you and others.
31+
32+
1233
.. prereq::
1334

1435
No computational prerequisites required for this lesson.
@@ -18,9 +39,10 @@ navigating and deciding on licenses.
1839
:widths: auto
1940
:delim: ;
2041

21-
15 min ; :doc:`social-coding`
22-
30 min ; :doc:`licensing`
23-
15 min ; :doc:`software-citation`
42+
20 min ; :doc:`social-coding`
43+
30 min ; :doc:`software-licensing`
44+
20 min ; :doc:`software-citation`
45+
10 min ; :doc:`sharing-data`
2446

2547

2648
.. toctree::
@@ -29,8 +51,9 @@ navigating and deciding on licenses.
2951
:hidden:
3052

3153
social-coding
32-
licensing
54+
software-licensing
3355
software-citation
56+
sharing-data
3457

3558

3659
.. _learner-personas:

0 commit comments

Comments
 (0)