Skip to content

feat: Configure lesson #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 11 additions & 13 deletions CITATION.cff
Original file line number Diff line number Diff line change
@@ -1,22 +1,20 @@
# This template CITATION.cff file was generated with cffinit.
# Visit https://bit.ly/cffinit to replace its contents
# with information about your lesson.
# Remember to update this file periodically,
# ensuring that the author list and other fields remain accurate.

cff-version: 1.2.0
title: FIXME
title: Reproducible Machine Learning Workflows for Scientists
message: >-
Please cite this lesson using the information in this file
when you refer to it in publications, and/or if you
re-use, adapt, or expand on the content in your own
training material.
type: dataset
type: software
authors:
- given-names: FIXME
family-names: FIXME
- given-names: "Matthew"
family-names: "Feickert"
orcid: "https://orcid.org/0000-0003-4124-7862"
- given-names: "Chris"
family-names: "Endemann"
- given-names: "Ryan"
family-names: "Bemowski"
abstract: >-
FIXME Replace this with a short abstract describing the
lesson, e.g. its target audience and main intended
learning objectives.
Provide an introduction to creating multi-platform fully reproducible
hardware accelerated and machine learning environment using Pixi.
license: CC-BY-4.0
86 changes: 14 additions & 72 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,83 +1,25 @@
# The Carpentries Workbench Template Markdown Lesson

This lesson is a template lesson that uses [The Carpentries Workbench][workbench].
This lesson is a template lesson that uses [The Carpentries Workbench][workbench].

## Note about lesson life cycle stage
Although the `config.yaml` states the life cycle stage as pre-alpha, **the template is stable and ready to use**. The life cycle stage is preset to `"pre-alpha"` as this setting is appropriate for new lessons initialised using the template.
## Using the lesson

## Create a new repository from this template
To step through the lesson, please follow it on its website at https://carpentries-incubator.github.io/reproducible-ml-workflows/

To use this template to start a new lesson repository,
make sure you're logged into Github.
Visit https://github.com/carpentries/workbench-template-md/generate
and follow the instructions.
Checking the 'Include all branches' option will save some time waiting for the first website build
when your new repository is initialised.
## Developing the lesson

If you have any questions, contact [@tobyhodges](https://github.com/tobyhodges)
Similar to the lesson itself, development of the lesson uses [Pixi](https://pixi.sh/) to have unified multi-platform reproducible environments.
To start developing:

## Configure a new lesson
1. [Install Pixi](https://pixi.sh/)
2. [Fork this repository on GitHub](https://github.com/carpentries-incubator/reproducible-ml-workflows/fork)
3. Clone your fork and navigate to the top level of the repository
4. Run

Follow the steps below to
complete the initial configuration of a new lesson repository built from this template:
```
pixi run start
```

1. **Make sure GitHub Pages is activated:**
navigate to _Settings_,
select _Pages_ from the left sidebar,
and make sure that `gh-pages` is selected as the branch to build from.
If no `gh-pages` branch is available, check _Actions_ to see if the first
website build workflows are still running.
The branch should become available when those have completed.
1. **Adjust the `config.yaml` file:**
this file contains global parameters for your lesson site.
Individual fields within the file are documented with comments (beginning with `#`)
At minimum, you should adjust all the fields marked 'FIXME':
- `title`
- `created`
- `keywords`
- `life_cycle` (the default, _pre-alpha_, is the appropriate for brand new lessons)
- `contact`
1. **Annotate the repository** with site URL and topic tags:
navigate back to the repository landing page and
click on the gear wheel/cog icon (similar to ⚙️)
at the top-right of the _About_ box.
Check the "Use your GitHub Pages website" option,
and [add some keywords and other annotations to describe your lesson](https://cdh.carpentries.org/the-carpentries-incubator.html#topic-tags)
in the _Topics_ field.
At minimum, these should include:
- `lesson`
- the life cycle of the lesson (e.g. `pre-alpha`)
- the human language the lesson is written in (e.g. `deutsch`)
1. **Adjust the
`CITATION.cff`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE.md` files**
as appropriate for your project.
- `CITATION.cff`:
this file contains information that people can use to cite your lesson,
for example if they publish their own work based on it.
You should [update the CFF][cff-sandpaper-docs] now to include information about your lesson,
and remember to return to it periodically, keeping it updated as your
author list grows and other details become available or need to change.
The [Citation File Format home page][cff-home] gives more information about the format,
and the [`cffinit` webtool][cffinit] can be used to create new and update existing CFF files.
- `CODE_OF_CONDUCT.md`:
if you are using this template for a project outside The Carpentries,
you should adjust this file to describe
who should be contacted with Code of Conduct reports,
and how those reports will be handled.
- `CONTRIBUTING.md`:
depending on the current state and maturity of your project,
the contents of the template Contributing Guide may not be appropriate.
You should adjust the file to help guide contributors on how best
to get involved and make an impact on your lesson.
- `LICENSE.md`:
in line with the terms of the CC-BY license,
you should ensure that the copyright information
provided in the license file is accurate for your project.
1. **Update this README with
[relevant information about your lesson](https://carpentries.github.io/lesson-development-training/collaborating-newcomers.html#readme)**
and delete this section.
and then open up the served site in your local browser and carry on with development.

[cff-home]: https://citation-file-format.github.io/
[cff-sandpaper-docs]: https://carpentries.github.io/sandpaper-docs/editing.html#making-your-lesson-citable
[cffinit]: https://citation-file-format.github.io/cff-initializer-javascript/
[workbench]: https://carpentries.github.io/sandpaper-docs/
23 changes: 12 additions & 11 deletions config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
# lc: Library Carpentry
# cp: Carpentries (to use for instructor training for instance)
# incubator: The Carpentries Incubator
#
#
# This option supports custom types so lessons can be branded
# and themed with your own logo and alt-text (see `carpentry_description`)
# See https://carpentries.github.io/sandpaper-docs/editing.html#adding-a-custom-logo
Expand All @@ -17,30 +17,31 @@ carpentry: 'incubator'
# Alt-text description of the lesson.
carpentry_description: 'Lesson Description'

# c.f. https://carpentries.github.io/sandpaper-docs/introduction.html
# Overall title for pages.
title: 'Lesson Title' # FIXME
title: 'Reproducible Machine Learning Workflows for Scientists'

# Date the lesson was created (YYYY-MM-DD, this is empty by default)
created: ~ # FIXME
created: 2025-03-16

# Comma-separated list of keywords for the lesson
keywords: 'software, data, lesson, The Carpentries' # FIXME
keywords: 'software, lesson, The Carpentries, machine learning, CUDA, hardware acceleration, reproducible'

# Life cycle stage of the lesson
# possible values: pre-alpha, alpha, beta, stable
life_cycle: 'pre-alpha' # FIXME
life_cycle: 'pre-alpha'

# License of the lesson
license: 'CC-BY 4.0'

# Link to the source repository for this lesson
source: 'https://github.com/carpentries/workbench-template-md' # FIXME
source: 'https://github.com/carpentries-incubator/reproducible-ml-workflows'

# Default branch of your lesson
branch: 'main'

# Who to contact if there are any issues
contact: '[email protected]' # FIXME
contact: '[email protected]'

# Navigation ------------------------------------------------
#
Expand All @@ -65,17 +66,17 @@ contact: '[email protected]' # FIXME
# - another-learner.md

# Order of episodes in your lesson
episodes:
episodes:
- introduction.md

# Information for Learners
learners:
learners:

# Information for Instructors
instructors:
instructors:

# Learner Profiles
profiles:
profiles:

# Customisation ---------------------------------------------
#
Expand Down