Skip to content

Commit 5cc328d

Browse files
matt-grahammatt-graham
committed
Initial commit
0 parents  commit 5cc328d

19 files changed

Lines changed: 3756 additions & 0 deletions

‎.github/workflows/render-quarto-slides.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Render Quarto slides template
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
pull_request:
8+
branches:
9+
- main
10+
schedule:
11+
- cron: 0 0 * * 0
12+
13+
concurrency:
14+
group: ${{ github.workflow }}-${{ github.ref }}
15+
cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
16+
17+
jobs:
18+
render:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout source
22+
uses: actions/checkout@v4
23+
- name: Setup Quarto
24+
uses: quarto-dev/quarto-actions/setup@v2
25+
- name: Check Quarto version
26+
run: quarto --version
27+
- name: Render Quarto slides
28+
run: quarto render . --to revealjs
29+
- name: Upload rendered slides as artifact
30+
uses: actions/upload-artifact@v4
31+
with:
32+
name: rendered-quarto-slides
33+
path: _output

‎.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
/.quarto/
2+
_output

‎2024-06-11-fdrs-workshop.qmd‎

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
---
2+
title: Festival of Digital Research and Scholarship
3+
date: 2024-06-11
4+
date-format: long
5+
institute: Centre for Advanced Research Computing
6+
title-image: https://raw.githubusercontent.com/UCL-ARC/python-tooling/main/images/banner.svg
7+
title-image-width: 70%
8+
background-image: images/arc-banner.svg
9+
title-slide-attributes:
10+
data-notes: |
11+
Hi, welcome to the python-tooling workshop. I'm {name} a {profession} at the UCL Advanced Research Computing Centre or ARC for short.
12+
We are going to start the workshop today by giving a brief overview and demo of the python-tooling project,
13+
which we've been working on in ARC to develop resources to assist researchers in choosing and setting up tooling to use in Python research software projects.
14+
After the demo is complete we will be running an interactive session
15+
where you will have a chance to try using the tools yourself.
16+
Myself and other ARC colleagues will be on hand to answer any questions you have
17+
and also to give advice using the tools in any existing Python research software projects you have.
18+
---
19+
20+
## 👥 Contributors {.smaller}
21+
22+
:::{.column width="80%"}
23+
24+
:::::: {.columns}
25+
::: {.column width="16.6%"}
26+
[![Paddy Roddy](https://avatars.githubusercontent.com/u/15052188?v=4?s=100)](https://paddyroddy.github.io/)
27+
:::
28+
::: {.column width="16.6%"}
29+
[![Sam Cunliffe](https://avatars.githubusercontent.com/u/1836192?v=4?s=100)](http://scnlf.me)
30+
:::
31+
::: {.column width="16.7%"}
32+
[![David Stansby](https://avatars.githubusercontent.com/u/6197628?v=4?s=100)](https://www.davidstansby.com/)
33+
:::
34+
::: {.column width="16.6%"}
35+
[![Matt Graham](https://avatars.githubusercontent.com/u/6746980?v=4?s=100)](http://matt-graham.github.io)
36+
:::
37+
::: {.column width="16.6%"}
38+
[![Sofía Miñano](https://avatars.githubusercontent.com/u/33267254?v=4?s=100)](https://sfmig.github.io/)
39+
:::
40+
::: {.column width="16.6%"}
41+
[![Paul Smith](https://avatars.githubusercontent.com/u/29753790?v=4?s=100)](https://github.com/p-j-smith/)
42+
:::
43+
:::
44+
45+
:::::: {.columns}
46+
::: {.column width="16.7%"}
47+
[![Ruaridh Gollifer](https://avatars.githubusercontent.com/u/32329546?v=4?s=100)](https://github.com/ruaridhg)
48+
:::
49+
::: {.column width="16.7%"}
50+
[![Miguel Xochicale](https://avatars.githubusercontent.com/u/11370681?v=4?s=100)](https://github.com/mxochicale)
51+
:::
52+
::: {.column width="16.6%"}
53+
[![Yidil Ozdemir](https://avatars.githubusercontent.com/u/30597301?v=4?s=100)](https://github.com/yidilozdemir)
54+
:::
55+
::: {.column width="16.7%"}
56+
[![Mosè Giordano](https://avatars.githubusercontent.com/u/765740?v=4?s=100)](https://giordano.github.io/)
57+
:::
58+
::: {.column width="16.6%"}
59+
[![Tom Young](https://avatars.githubusercontent.com/u/39765193?v=4?s=100)](http://t-young31.github.io/)
60+
:::
61+
::: {.column width="16.7%"}
62+
[![Alessandro Felder](https://avatars.githubusercontent.com/u/10500965?v=4?s=100)](https://github.com/alessandrofelder)
63+
:::
64+
:::
65+
66+
:::::: {.columns}
67+
::: {.column width="16.7%"}
68+
[![Adam Tyson](https://avatars.githubusercontent.com/u/13147259?v=4?s=100)](http://adamltyson.com/)
69+
:::
70+
::: {.column width="16.7%"}
71+
[![Will Graham](https://avatars.githubusercontent.com/u/32364977?v=4?s=100)](https://willgraham01.github.io/)
72+
:::
73+
::: {.column width="16.6%"}
74+
[![Nik Khadijah Nik Aznan](https://avatars.githubusercontent.com/u/48319650?v=4?s=100)](https://github.com/nikk-nikaznan)
75+
:::
76+
::: {.column width="16.7%"}
77+
[![Katie Buntić](https://avatars.githubusercontent.com/u/96536608?v=4?s=100)](https://github.com/katiebuntic)
78+
:::
79+
::: {.column width="16.6%"}
80+
[![Robert Vickerstaff](https://avatars.githubusercontent.com/u/456100?v=4?s=100)](https://github.com/robertvi)
81+
:::
82+
::: {.column width="16.7%"}
83+
[![David Pérez-Suárez](https://avatars.githubusercontent.com/u/963242?v=4?s=100)](http://dpshelio.github.io)
84+
:::
85+
:::
86+
87+
:::
88+
89+
:::notes
90+
This project is the result of the contributions of a large number of people from across ARC and also other departments in UCL such as the Department of Mechanical Engineering and Sainsburys Wellcome Centre. Of particular note are David Stansby, who had the initial idea and organized the original doc-a-thon sessions which got the ball rolling on the project, and Paddy Roddy and Sam Cunliffe, who both have made significant contributions and done a lot of the on-going event organization and project management.
91+
:::
92+
93+
## 💡 Introduction
94+
95+
:::::: {.columns}
96+
::: {.column .fragment width="25%"}
97+
![](https://upload.wikimedia.org/wikipedia/commons/c/c3/Python-logo-notext.svg){height="300px"}
98+
:::
99+
::: {.column .fragment width="25%"}
100+
![](images/pypi-logo.svg){height="300px"}
101+
:::
102+
::: {.column .fragment width="25%"}
103+
![](images/paralysis-of-choice.svg){height="300px"}
104+
:::
105+
::: {.column .fragment width="25%"}
106+
![](https://raw.githubusercontent.com/UCL-ARC/python-tooling/main/images/logo.svg){height="300px"}
107+
:::
108+
:::
109+
110+
:::notes
111+
To give a bit of initial context:
112+
113+
The Python programming language is widely used in research software, due to its ease of use, wide ecosystem of existing libraries and open-source licencing.
114+
115+
Python packages are a way to organize Python code into reusable components, and so are a vital part of building sustainable research software in Python.
116+
117+
A common dilemma faced by researchers using Python is the paralysis of choice that comes from the incredibly wide range of tools available for developing, testing, documenting and benchmarking Python packages, with it often unclear what constitutes good choices of tools to use.
118+
119+
The `python-tooling` project is a set of resources developed by UCL ARC to help researchers in choosing and setting up tooling to use in Python research software projects.
120+
:::
121+
122+
## 🔎 Overview
123+
124+
:::{.no-bullet}
125+
- 🚦 Tool recommendations website <br /> <https://github-pages.arc.ucl.ac.uk/python-tooling>
126+
- 🍪 Package cookiecutter template <br /> <https://github.com/UCL-ARC/python-tooling>
127+
:::
128+
129+
:::notes
130+
The project consists of
131+
132+
- a website which uses a traffic light system to give recommendations on tools and services that are useful when building a Python package,
133+
- and a cookiecutter template that can be used to quickly set up a Python package with our tooling recommendations to ensure that a new project adheres with good research software development practice.
134+
:::
135+
136+
## 🚦 Tool recommendations website
137+
138+
:::notes
139+
The website has pages giving recommendations on a range of different categories of tools and services, such as utilities for benchmarking and profiling code to improve performance, generating documentation and writing and running tests.
140+
141+
On each page a table listing relevant tools and packages with a link to the package or service, a short summary and a traffic light recommendation for each.
142+
143+
The traffic lights are meant to give a quick opinionated suggestion of the tools we most recommend for a particular task.
144+
:::
145+
146+
```{=html}
147+
<iframe src="https://github-pages.arc.ucl.ac.uk/python-tooling" title="UCL ARC Python tooling website" width="1000" height="500" style="border:none;" ></iframe>
148+
```
149+
150+
## 🍪 Template demo
151+
152+
:::notes
153+
We'll now give a short demo of how the cookiecutter template can be used by researchers to quickly create a Python package which integrates lots of elements of good practice in creating sustainable research software such as use of Git for version control, automated testing and linting and a documentation website.
154+
155+
To create an instance of template you will need to first install the `cookiecutter` package (for example using `conda`) and then run
156+
```
157+
cookiecutter gh:ucl-arc/python-tooling
158+
```
159+
160+
(Briefly explain prompts, using default options other than
161+
162+
```
163+
[4/14] Name of project: Festival of DRS demo
164+
[9/14] Automatically deploy HTML docs?: Y
165+
[10/14] GitHub owner: UCL-ARC
166+
```
167+
168+
for later commands and links to work)
169+
170+
You will then get some helpful output telling you to run
171+
172+
```
173+
gh repo create UCL-ARC/festival-of-drs-demo -d 'A cookiecutter package with UCL ARC recommendations.' --public -r origin --source festival-of-drs-demo
174+
```
175+
176+
to create a repository on GitHub for the project if you have the GitHub command line interface installed.
177+
178+
As we selected to deploy the documentation to GitHub pages we are also told some further configuration to the repository we need to do, namely to go to
179+
180+
https://github.com/UCL-ARC/festival-of-drs-demo/settings/actions
181+
182+
and set `Workflow permissions` to `Read and write permissions`
183+
184+
Once we have done that we can then make an initial commit and push to our newly created repository on GitHub
185+
186+
```
187+
cd festival-of-drs-demo
188+
git add .
189+
git commit -m "Initial commit"
190+
git push --set-upstream origin main
191+
```
192+
193+
If we now go to
194+
195+
https://github.com/UCL-ARC/festival-of-drs-demo/
196+
197+
we can see the repository is now populated with a README with some default content such as the project description, details of the project team, instructions for installing the package, running the tests and building the documentation locally (navigate to each of these sections in README). Using GitHub's Citation File Format support we also have an easy way to automatically generate a citation for the repository (demo 'Cite this repository' button ).
198+
199+
The repository has also been set up with automated workflows for running tests, performing linting static analysis checks on the source code and building the documentation the status of which we can see from the badges on README page (show badges) or by going to the Actions pane
200+
201+
https://github.com/UCL-ARC/python-tooling/actions
202+
203+
(Wait for `Documentation` workflow to complete to ensure `gh-pages` branch has been created and pushed to.)
204+
205+
To enable the GitHub Page website for the repository there is one final step we need to do that is also printed in the message output by the `cookiecutter` command, which is to go to the settings page at
206+
207+
https://github.com/UCL-ARC/festival-of-drs-demo/settings/pages
208+
209+
and under 'Built and deployment' selecting 'Deploy from a branch' for the 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, leaving the branch path drop-down with its default value of '/ (root)'.
210+
211+
Once the documentation deploy action has finished running
212+
213+
https://github.com/UCL-ARC/python-tooling/actions
214+
215+
(Wait for `pages-build-deployment` action to complete)
216+
217+
the documentation can then be viewed at
218+
219+
https://github-pages.arc.ucl.ac.uk/festival-of-drs-demo
220+
221+
The documentation site homepage is automatically set up to show the content from the repository README. Importantly however we also get automatically generated API documentation from the docstrings in the source code (go to API reference page). The project LICENSE is also displayed in documentation (go to License page).
222+
:::
223+
224+
## 👨‍🏫 Tutorial
225+
226+
![](images/2024-tutorial-qr-code.svg)
227+
228+
<https://tinyurl.com/python-tooling-tutorial>

0 commit comments

Comments
 (0)
⚡