Skip to content

Commit 4052af7

Browse files
committed
Lint the text & markdown files & fix spelling
1 parent 29f220f commit 4052af7

31 files changed

+227
-197
lines changed

.github/workflows/README.md

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ R console:
1010

1111
```r
1212
# Install/Update sandpaper
13-
options(repos = c(carpentries = "https://carpentries.r-universe.dev/",
13+
options(repos = c(carpentries = "https://carpentries.r-universe.dev/",
1414
CRAN = "https://cloud.r-project.org"))
1515
install.packages("sandpaper")
1616

@@ -42,13 +42,13 @@ This workflow does the following:
4242

4343
#### Caching
4444

45-
This workflow has two caches; one cache is for the lesson infrastructure and
45+
This workflow has two caches; one cache is for the lesson infrastructure and
4646
the other is for the the lesson dependencies if the lesson contains rendered
4747
content. These caches are invalidated by new versions of the infrastructure and
48-
the `renv.lock` file, respectively. If there is a problem with the cache,
48+
the `renv.lock` file, respectively. If there is a problem with the cache,
4949
manual invaliation is necessary. You will need maintain access to the repository
5050
and you can either go to the actions tab and [click on the caches button to find
51-
and invalidate the failing cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/)
51+
and invalidate the failing cache](https://github.blog/changelog/2022-10-20-manage-caches-in-your-actions-workflows-from-web-interface/)
5252
or by setting the `CACHE_VERSION` secret to the current date (which will
5353
invalidate all of the caches).
5454

@@ -58,32 +58,32 @@ invalidate all of the caches).
5858

5959
These workflows run on a schedule and at the maintainer's request. Because they
6060
create pull requests that update workflows/require the downstream actions to run,
61-
they need a special repository/organization secret token called
62-
`SANDPAPER_WORKFLOW` and it must have the `public_repo` and `workflow` scope.
61+
they need a special repository/organization secret token called
62+
`SANDPAPER_WORKFLOW` and it must have the `public_repo` and `workflow` scope.
6363

6464
This can be an individual user token, OR it can be a trusted bot account. If you
6565
have a repository in one of the official Carpentries accounts, then you do not
6666
need to worry about this token being present because the Carpentries Core Team
6767
will take care of supplying this token.
6868

69-
If you want to use your personal account: you can go to
69+
If you want to use your personal account: you can go to
7070
<https://github.com/settings/tokens/new?scopes=public_repo,workflow&description=Sandpaper%20Token>
7171
to create a token. Once you have created your token, you should copy it to your
7272
clipboard and then go to your repository's settings > secrets > actions and
7373
create or edit the `SANDPAPER_WORKFLOW` secret, pasting in the generated token.
7474

7575
If you do not specify your token correctly, the runs will not fail and they will
76-
give you instructions to provide the token for your repository.
76+
give you instructions to provide the token for your repository.
7777

7878
### 02 Maintain: Update Workflow Files (update-workflow.yaml)
7979

80-
The {sandpaper} repository was designed to do as much as possible to separate
81-
the tools from the content. For local builds, this is absolutely true, but
82-
there is a minor issue when it comes to workflow files: they must live inside
83-
the repository.
80+
The {sandpaper} repository was designed to do as much as possible to separate
81+
the tools from the content. For local builds, this is absolutely true, but
82+
there is a minor issue when it comes to workflow files: they must live inside
83+
the repository.
8484

8585
This workflow ensures that the workflow files are up-to-date. The way it work is
86-
to download the update-workflows.sh script from GitHub and run it. The script
86+
to download the update-workflows.sh script from GitHub and run it. The script
8787
will do the following:
8888

8989
1. check the recorded version of sandpaper against the current version on github
@@ -100,25 +100,25 @@ This update is run weekly or on demand.
100100

101101
For lessons that have generated content, we use {renv} to ensure that the output
102102
is stable. This is controlled by a single lockfile which documents the packages
103-
needed for the lesson and the version numbers. This workflow is skipped in
103+
needed for the lesson and the version numbers. This workflow is skipped in
104104
lessons that do not have generated content.
105105

106106
Because the lessons need to remain current with the package ecosystem, it's a
107-
good idea to make sure these packages can be updated periodically. The
107+
good idea to make sure these packages can be updated periodically. The
108108
update cache workflow will do this by checking for updates, applying them in a
109109
branch called `updates/packages` and creating a pull request with _only the
110-
lockfile changed_.
110+
lockfile changed_.
111111

112112
From here, the markdown documents will be rebuilt and you can inspect what has
113-
changed based on how the packages have updated.
113+
changed based on how the packages have updated.
114114

115115
## Pull Request and Review Management
116116

117-
Because our lessons execute code, pull requests are a secruity risk for any
118-
lesson and thus have security measures associted with them. **Do not merge any
117+
Because our lessons execute code, pull requests are a security risk for any
118+
lesson and thus have security measures associated with them. **Do not merge any
119119
pull requests that do not pass checks and do not have bots commented on them.**
120120

121-
This series of workflows all go together and are described in the following
121+
This series of workflows all go together and are described in the following
122122
diagram and the below sections:
123123

124124
![Graph representation of a pull request](https://carpentries.github.io/sandpaper/articles/img/pr-flow.dot.svg)
@@ -129,22 +129,22 @@ This workflow runs every time a pull request is created and its purpose is to
129129
validate that the pull request is okay to run. This means the following things:
130130

131131
1. The pull request does not contain modified workflow files
132-
2. If the pull request contains modified workflow files, it does not contain
132+
2. If the pull request contains modified workflow files, it does not contain
133133
modified content files (such as a situation where @carpentries-bot will
134134
make an automated pull request)
135135
3. The pull request does not contain an invalid commit hash (e.g. from a fork
136136
that was made before a lesson was transitioned from styles to use the
137137
workbench).
138138

139-
Once the checks are finished, a comment is issued to the pull request, which
140-
will allow maintainers to determine if it is safe to run the
139+
Once the checks are finished, a comment is issued to the pull request, which
140+
will allow maintainers to determine if it is safe to run the
141141
"Receive Pull Request" workflow from new contributors.
142142

143143
### Receive Pull Request (pr-receive.yaml)
144144

145145
**Note of caution:** This workflow runs arbitrary code by anyone who creates a
146146
pull request. GitHub has safeguarded the token used in this workflow to have no
147-
priviledges in the repository, but we have taken precautions to protect against
147+
privileges in the repository, but we have taken precautions to protect against
148148
spoofing.
149149

150150
This workflow is triggered with every push to a pull request. If this workflow
@@ -154,8 +154,8 @@ started.
154154

155155
The first step of this workflow is to check if it is valid (e.g. that no
156156
workflow files have been modified). If there are workflow files that have been
157-
modified, a comment is made that indicates that the workflow is not run. If
158-
both a workflow file and lesson content is modified, an error will occurr.
157+
modified, a comment is made that indicates that the workflow is not run. If
158+
both a workflow file and lesson content is modified, an error will occur.
159159

160160
The second step (if valid) is to build the generated content from the pull
161161
request. This builds the content and uploads three artifacts:
@@ -164,7 +164,7 @@ request. This builds the content and uploads three artifacts:
164164
2. A summary of changes after the rendering process (diff)
165165
3. The rendered files (build)
166166

167-
Because this workflow builds generated content, it follows the same general
167+
Because this workflow builds generated content, it follows the same general
168168
process as the `sandpaper-main` workflow with the same caching mechanisms.
169169

170170
The artifacts produced are used by the next workflow.
@@ -183,9 +183,9 @@ The steps in this workflow are:
183183
Importantly: if the pull request is invalid, the branch is not created so any
184184
malicious code is not published.
185185

186-
From here, the maintainer can request changes from the author and eventually
187-
either merge or reject the PR. When this happens, if the PR was valid, the
188-
preview branch needs to be deleted.
186+
From here, the maintainer can request changes from the author and eventually
187+
either merge or reject the PR. When this happens, if the PR was valid, the
188+
preview branch needs to be deleted.
189189

190190
### Send Close PR Signal (pr-close-signal.yaml)
191191

@@ -194,5 +194,5 @@ pull request number for the next action
194194

195195
### Remove Pull Request Branch (pr-post-remove-branch.yaml)
196196

197-
Tiggered by `pr-close-signal.yaml`. This removes the temporary branch associated with
197+
Triggered by `pr-close-signal.yaml`. This removes the temporary branch associated with
198198
the pull request (if it was created).

.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,4 +61,4 @@ __pycache__/
6161
.dir-locals.el
6262

6363
# OSX
64-
.DS_Store
64+
.DS_Store

.markdownlint-cli2.yaml

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
config:
2+
3+
line_length:
4+
line_length: 120
5+
code_blocks: false
6+
tables: false
7+
html:
8+
allowed_elements:
9+
- div
10+
no-duplicate-heading: false
11+
12+
globs:
13+
14+
- "**/*.md"
15+
- "*.md"
16+
17+
ignores:
18+
19+
- "site/**/*.md"
20+
- ".github/**/*.md"
21+
- "renv/**/*.md"
22+
23+
fix: true

.pre-commit-config.yaml

Lines changed: 27 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,30 @@
11
# See https://pre-commit.com for more information
22
# See https://pre-commit.com/hooks.html for more hooks
33
repos:
4-
- repo: https://github.com/pre-commit/pre-commit-hooks
5-
rev: v3.2.0
6-
hooks:
7-
- id: trailing-whitespace
8-
- id: end-of-file-fixer
9-
- id: check-yaml
10-
- id: check-added-large-files
4+
- repo: https://github.com/pre-commit/pre-commit-hooks
5+
rev: v6.0.0
6+
hooks:
7+
- id: check-added-large-files
8+
args: ['--maxkb=2048']
9+
- id: check-merge-conflict
10+
- id: check-yaml
11+
- id: end-of-file-fixer
12+
- id: no-commit-to-branch
13+
- id: trailing-whitespace
14+
15+
- repo: https://github.com/DavidAnson/markdownlint-cli2
16+
rev: v0.18.1
17+
hooks:
18+
- id: markdownlint-cli2
19+
args: []
20+
- repo: https://github.com/codespell-project/codespell
21+
rev: v2.4.1
22+
hooks:
23+
- id: codespell
24+
25+
ci:
26+
autofix_prs: true
27+
autofix_commit_msg: '[pre-commit.ci] Fixing issues with pre-commit'
28+
autoupdate_schedule: weekly
29+
autoupdate_commit_msg: '[pre-commit.ci] pre-commit-autoupdate'
30+
skip: [] # Optionally list ids of hooks to skip on CI

CONTRIBUTING.md

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
1-
## Contributing
1+
# Contributing
22

33
We welcome contributions to this open educational resource: fixes to
44
existing material, bug reports, and reviews of proposed changes are all
55
welcome.
66

7-
### Contributor Agreement
7+
## Contributor Agreement
88

99
By contributing, you agree that we may redistribute your work under [our
1010
license](LICENSE.md). In exchange, we will address your issues and/or assess
1111
your change proposal as promptly as we can, and help you become a member of our
1212
community. All contributors agree to abide by
1313
our [code of conduct](CODE_OF_CONDUCT.md).
1414

15-
### How to Contribute
15+
## How to Contribute
1616

1717
1. If you do not have a [GitHub][github] account, you can [send us comments by
1818
email][contact]. However, we will be able to respond more quickly if you use
@@ -28,9 +28,9 @@ our [code of conduct](CODE_OF_CONDUCT.md).
2828
[included below](#using-github).
2929

3030
Note: if you want to build the website locally, please refer to [The Workbench
31-
documentation][template-doc].
31+
documentation](template-doc).
3232

33-
### Using GitHub
33+
## Using GitHub
3434

3535
If you choose to contribute via GitHub, you may want to look at [How to
3636
Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we
@@ -53,4 +53,3 @@ NB: The published copy of the lesson is usually in the `main` branch.
5353
[github-flow]: https://guides.github.com/introduction/flow/
5454
[github-join]: https://github.com/join
5555
[how-contribute]: https://egghead.io/courses/how-to-contribute-to-an-open-source-project-on-github
56-
[template-doc]: https://carpentries.github.io/workbench/

README.md

Lines changed: 22 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,11 +6,14 @@ This lesson uses [The Carpentries Workbench][workbench] template.
66

77
## Course Description
88

9-
Whether you are a seasoned developer or just write the occasional script, it's important to know that your code does what you intend, and will continue to do so as you make changes.
9+
Whether you are a seasoned developer or just write the occasional script, it's important to know that your code does
10+
what you intend, and will continue to do so as you make changes.
1011

11-
Software testing is a methodology of automatically ensuring that your code works correctly, without having to go back and manually verify after each change.
12+
Software testing is a methodology of automatically ensuring that your code works correctly, without having to go back
13+
and manually verify after each change.
1214

13-
This course seeks to provide you with conceptual understanding and the tools you need to start ensuring the robustness of your code.
15+
This course seeks to provide you with conceptual understanding and the tools you need to start ensuring the robustness
16+
of your code.
1417

1518
### Contents
1619

@@ -26,28 +29,31 @@ This course seeks to provide you with conceptual understanding and the tools you
2629

2730
## Contributions
2831

29-
Contributions are welcome, please refer to the [contribution guidelines](CONTRIBUTING.md) of how to do so and ensure that you adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
32+
Contributions are welcome, please refer to the [contribution guidelines](CONTRIBUTING.md) of how to do so and ensure
33+
that you adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
3034

3135
### Build the lesson locally
3236

33-
To render the lesson locally, you will need to have [R][r] installed. Instructions for using R with the Carpentries template is [available](https://carpentries.github.io/workbench/#installation) but some additional setps have been taken to make sure the enivronment is reproducible using the [`{renv}`](https://rstudio.github.io/renv/articles/renv.html) package and an `renv.lockfile` is included which allows the environment to be re-created along with dependencies.
37+
To render the lesson locally, you will need to have [R][rlang] installed. Instructions for using R with the Carpentries
38+
template is [available](https://carpentries.github.io/workbench/#installation) but some additional setps have been
39+
taken to make sure the environment is reproducible using the
40+
[`{renv}`](https://rstudio.github.io/renv/articles/renv.html) package and an `renv.lockfile` is included which allows
41+
the environment to be re-created along with dependencies.
3442

3543
After cloning the repository, you can set up the `renv` and install all packages with:
36-
``` r
44+
3745
renv::restore()
38-
# Optionally update packages
46+
3947
renv::update()
48+
4049
```
41-
Once you have installed the dependencies, you can render the pages locally by starting R in the project root and running:
50+
51+
Once you have installed the dependencies, you can render the pages locally by starting R in the project root and
52+
running:
4253
``` r
4354
sandpaper::serve()
44-
```
45-
This will build the pages and start a local web-server in R and open it in your browser. These pages are "live" and will respond to local file changes if you save them.
55+
This will build the pages and start a local web-server in R and open it in your browser. These pages are "live" and
56+
will respond to local file changes if you save them.
4657
47-
[git]: https://git-scm.com
48-
[r]: https://www.r-project.org/
58+
[rlang]: https://www.r-project.org/
4959
[workbench]: https://carpentries.github.io/workbench/
50-
51-
52-
53-

config.yaml

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -86,5 +86,3 @@ profiles:
8686
# sandpaper and varnish versions) should live
8787
varnish: RSE-Sheffield/uos-varnish@main
8888
url: 'https://sylviawhittle.github.io/python-testing-for-research/'
89-
90-

episodes/00-introduction.Rmd

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ teaching: 10
44
exercises: 2
55
---
66

7-
:::::::::::::::::::::::::::::::::::::: questions
7+
:::::::::::::::::::::::::::::::::::::: questions
88

99
- What are the goals of this course?
1010

@@ -29,15 +29,15 @@ By the end of this course, you should:
2929
- Understand how testing can be used to improve code & research reliability
3030
- Be comfortable with writing basic tests & running them
3131
- Be able to construct a simple Python project that incorporates tests
32-
- Be familiar with testing best practices such as unit testing & the AAA pattern
32+
- Be familiar with testing best practices such as unit testing & the AAA pattern
3333
- Be aware of more advanced testing features such as fixtures & parametrization
3434
- Understand what Continuous Integration is and why it is useful
3535
- Be able to add testing to a GitHub repository with simple Continuous Integration
3636

3737

3838
## Code of Conduct
3939

40-
This course is covered by the [Carpentries Code of Conduct](https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html).
40+
This course is covered by the [Carpentries Code of Conduct](https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html).
4141

4242
As mentioned in the Carpentries Code of Conduct, we encourage you to:
4343

@@ -70,11 +70,10 @@ This course uses blocks like the one below to indicate an exercise for you to at
7070

7171
::::::::::::::::::::::::::::::::::::::::::::::::
7272

73-
::::::::::::::::::::::::::::::::::::: keypoints
73+
::::::::::::::::::::::::::::::::::::: keypoints
7474

7575
- This course will teach you how to write effective tests and ensure the quality and reliability of your research software
7676
- No prior testing experience is required
7777
- You can catch up on practicals by copying the corresponding folder from the `files` directory of this course's materials
7878

7979
::::::::::::::::::::::::::::::::::::::::::::::::
80-

0 commit comments

Comments
 (0)