|
1 | 1 | # The Carpentries Workbench Template Markdown Lesson |
2 | 2 |
|
3 | | -This lesson is a template lesson that uses [The Carpentries Workbench][workbench]. |
| 3 | +This lesson is a template lesson that uses [The Carpentries Workbench][workbench]. |
4 | 4 |
|
5 | | -## Note about lesson life cycle stage |
6 | | -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. |
| 5 | +## Using the lesson |
7 | 6 |
|
8 | | -## Create a new repository from this template |
| 7 | +To step through the lesson, please follow it on its website at https://carpentries-incubator.github.io/reproducible-ml-workflows/ |
9 | 8 |
|
10 | | -To use this template to start a new lesson repository, |
11 | | -make sure you're logged into Github. |
12 | | -Visit https://github.com/carpentries/workbench-template-md/generate |
13 | | -and follow the instructions. |
14 | | -Checking the 'Include all branches' option will save some time waiting for the first website build |
15 | | -when your new repository is initialised. |
| 9 | +## Developing the lesson |
16 | 10 |
|
17 | | -If you have any questions, contact [@tobyhodges](https://github.com/tobyhodges) |
| 11 | +Similar to the lesson itself, development of the lesson uses [Pixi](https://pixi.sh/) to have unified multi-platform reproducible environments. |
| 12 | +To start developing: |
18 | 13 |
|
19 | | -## Configure a new lesson |
| 14 | +1. [Install Pixi](https://pixi.sh/) |
| 15 | +2. [Fork this repository on GitHub](https://github.com/carpentries-incubator/reproducible-ml-workflows/fork) |
| 16 | +3. Clone your fork and navigate to the top level of the repository |
| 17 | +4. Run |
20 | 18 |
|
21 | | -Follow the steps below to |
22 | | -complete the initial configuration of a new lesson repository built from this template: |
| 19 | +``` |
| 20 | +pixi run start |
| 21 | +``` |
23 | 22 |
|
24 | | -1. **Make sure GitHub Pages is activated:** |
25 | | - navigate to _Settings_, |
26 | | - select _Pages_ from the left sidebar, |
27 | | - and make sure that `gh-pages` is selected as the branch to build from. |
28 | | - If no `gh-pages` branch is available, check _Actions_ to see if the first |
29 | | - website build workflows are still running. |
30 | | - The branch should become available when those have completed. |
31 | | -1. **Adjust the `config.yaml` file:** |
32 | | - this file contains global parameters for your lesson site. |
33 | | - Individual fields within the file are documented with comments (beginning with `#`) |
34 | | - At minimum, you should adjust all the fields marked 'FIXME': |
35 | | - - `title` |
36 | | - - `created` |
37 | | - - `keywords` |
38 | | - - `life_cycle` (the default, _pre-alpha_, is the appropriate for brand new lessons) |
39 | | - - `contact` |
40 | | -1. **Annotate the repository** with site URL and topic tags: |
41 | | - navigate back to the repository landing page and |
42 | | - click on the gear wheel/cog icon (similar to ⚙️) |
43 | | - at the top-right of the _About_ box. |
44 | | - Check the "Use your GitHub Pages website" option, |
45 | | - and [add some keywords and other annotations to describe your lesson](https://cdh.carpentries.org/the-carpentries-incubator.html#topic-tags) |
46 | | - in the _Topics_ field. |
47 | | - At minimum, these should include: |
48 | | - - `lesson` |
49 | | - - the life cycle of the lesson (e.g. `pre-alpha`) |
50 | | - - the human language the lesson is written in (e.g. `deutsch`) |
51 | | -1. **Adjust the |
52 | | - `CITATION.cff`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and `LICENSE.md` files** |
53 | | - as appropriate for your project. |
54 | | - - `CITATION.cff`: |
55 | | - this file contains information that people can use to cite your lesson, |
56 | | - for example if they publish their own work based on it. |
57 | | - You should [update the CFF][cff-sandpaper-docs] now to include information about your lesson, |
58 | | - and remember to return to it periodically, keeping it updated as your |
59 | | - author list grows and other details become available or need to change. |
60 | | - The [Citation File Format home page][cff-home] gives more information about the format, |
61 | | - and the [`cffinit` webtool][cffinit] can be used to create new and update existing CFF files. |
62 | | - - `CODE_OF_CONDUCT.md`: |
63 | | - if you are using this template for a project outside The Carpentries, |
64 | | - you should adjust this file to describe |
65 | | - who should be contacted with Code of Conduct reports, |
66 | | - and how those reports will be handled. |
67 | | - - `CONTRIBUTING.md`: |
68 | | - depending on the current state and maturity of your project, |
69 | | - the contents of the template Contributing Guide may not be appropriate. |
70 | | - You should adjust the file to help guide contributors on how best |
71 | | - to get involved and make an impact on your lesson. |
72 | | - - `LICENSE.md`: |
73 | | - in line with the terms of the CC-BY license, |
74 | | - you should ensure that the copyright information |
75 | | - provided in the license file is accurate for your project. |
76 | | -1. **Update this README with |
77 | | - [relevant information about your lesson](https://carpentries.github.io/lesson-development-training/collaborating-newcomers.html#readme)** |
78 | | - and delete this section. |
| 23 | +and then open up the served site in your local browser and carry on with development. |
79 | 24 |
|
80 | | -[cff-home]: https://citation-file-format.github.io/ |
81 | | -[cff-sandpaper-docs]: https://carpentries.github.io/sandpaper-docs/editing.html#making-your-lesson-citable |
82 | | -[cffinit]: https://citation-file-format.github.io/cff-initializer-javascript/ |
83 | 25 | [workbench]: https://carpentries.github.io/sandpaper-docs/ |
0 commit comments