From b608476843a8a855587d7faf5cb2d42e06629e31 Mon Sep 17 00:00:00 2001 From: Martin Kwok Date: Wed, 27 Dec 2023 23:54:42 +0100 Subject: [PATCH] init --- AUTHORS | 1 + CITATION | 1 + CONTRIBUTING.md | 151 +++++++++++++++++++++++++++++++++++ README.md | 40 ++++++++++ _config.yml | 120 ++++++++++++++++++++++++++++ _episodes/01-introduction.md | 15 ++++ _extras/about.md | 5 ++ _extras/discuss.md | 6 ++ _extras/figures.md | 79 ++++++++++++++++++ _extras/guide.md | 6 ++ index.md | 17 ++++ reference.md | 9 +++ setup.md | 7 ++ 13 files changed, 457 insertions(+) create mode 100644 AUTHORS create mode 100644 CITATION create mode 100644 CONTRIBUTING.md create mode 100644 README.md create mode 100644 _config.yml create mode 100644 _episodes/01-introduction.md create mode 100644 _extras/about.md create mode 100644 _extras/discuss.md create mode 100644 _extras/figures.md create mode 100644 _extras/guide.md create mode 100644 index.md create mode 100644 reference.md create mode 100644 setup.md diff --git a/AUTHORS b/AUTHORS new file mode 100644 index 0000000..04e1f5a --- /dev/null +++ b/AUTHORS @@ -0,0 +1 @@ +FIXME: list authors' names and email addresses. \ No newline at end of file diff --git a/CITATION b/CITATION new file mode 100644 index 0000000..56ece3c --- /dev/null +++ b/CITATION @@ -0,0 +1 @@ +FIXME: describe how to cite this lesson. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8c095d8 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,151 @@ +# Contributing + +[The Carpentries][c-site] ([Software Carpentry][swc-site], [Data Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source projects, +and we welcome contributions of all kinds: +new lessons, +fixes to existing material, +bug reports, +and reviews of proposed changes are all welcome. + +## Contributor Agreement + +By contributing, +you agree that we may redistribute your work under [our license](LICENSE.md). +In exchange, +we will address your issues and/or assess your change proposal as promptly as we can, +and help you become a member of our community. +Everyone involved in [The Carpentries][c-site] +agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md). + +## How to Contribute + +The easiest way to get started is to file an issue +to tell us about a spelling mistake, +some awkward wording, +or a factual error. +This is a good way to introduce yourself +and to meet some of our community members. + +1. If you do not have a [GitHub][github] account, + you can [send us comments by email][email]. + However, + we will be able to respond more quickly if you use one of the other methods described below. + +2. If you have a [GitHub][github] account, + or are willing to [create one][github-join], + but do not know how to use Git, + you can report problems or suggest improvements by [creating an issue][issues]. + This allows us to assign the item to someone + and to respond to it in a threaded discussion. + +3. If you are comfortable with Git, + and would like to add or change material, + you can submit a pull request (PR). + Instructions for doing this are [included below](#using-github). + +## Where to Contribute + +1. If you wish to change this lesson, + please work in , + which can be viewed at . + +2. If you wish to change the example lesson, + please work in , + which documents the format of our lessons + and can be viewed at . + +3. If you wish to change the template used for workshop websites, + please work in . + The home page of that repository explains how to set up workshop websites, + while the extra pages in + provide more background on our design choices. + +4. If you wish to change CSS style files, tools, + or HTML boilerplate for lessons or workshops stored in `_includes` or `_layouts`, + please work in . + +## What to Contribute + +There are many ways to contribute, +from writing new exercises and improving existing ones +to updating or filling in the documentation +and submitting [bug reports][issues] +about things that do not work, are not clear, or are missing. +If you are looking for ideas, please see the 'Issues' tab for +a list of issues associated with this repository, +or you may also look at the issues for [Data Carpentry][dc-issues], +[Software Carpentry][swc-issues], and [Library Carpentry][lc-issues] projects. + +Comments on issues and reviews of pull requests are just as welcome: +we are smarter together than we are on our own. +Reviews from novices and newcomers are particularly valuable: +it is easy for people who have been using these lessons for a while +to forget how impenetrable some of this material can be, +so fresh eyes are always welcome. + +## What *Not* to Contribute + +Our lessons already contain more material than we can cover in a typical workshop, +so we are usually *not* looking for more concepts or tools to add to them. +As a rule, +if you want to introduce a new idea, +you must (a) estimate how long it will take to teach +and (b) explain what you would take out to make room for it. +The first encourages contributors to be honest about requirements; +the second, to think hard about priorities. + +We are also not looking for exercises or other material that will only run on one platform. +Our workshops typically contain a mixture of Windows, macOS, and Linux users; +in order to be usable, +our lessons must run equally well on all three. + +## Using GitHub + +If you choose to contribute via GitHub, you may want to look at +[How to Contribute to an Open Source Project on GitHub][how-contribute]. +To manage changes, we follow [GitHub flow][github-flow]. +Each lesson has at least two maintainers who review issues and pull requests or encourage others to do so. +The maintainers are community volunteers and have final say over what gets merged into the lesson. +To use the web interface for contributing to a lesson: + +1. Fork the originating repository to your GitHub profile. +2. Within your version of the forked repository, move to the `gh-pages` branch and +create a new branch for each significant change being made. +3. Navigate to the file(s) you wish to change within the new branches and make revisions as required. +4. Commit all changed files within the appropriate branches. +5. Create individual pull requests from each of your changed branches +to the `gh-pages` branch within the originating repository. +6. If you receive feedback, make changes using your issue-specific branches of the forked +repository and the pull requests will update automatically. +7. Repeat as needed until all feedback has been addressed. + +When starting work, please make sure your clone of the originating `gh-pages` branch is up-to-date +before creating your own revision-specific branch(es) from there. +Additionally, please only work from your newly-created branch(es) and *not* +your clone of the originating `gh-pages` branch. +Lastly, published copies of all the lessons are available in the `gh-pages` branch of the originating +repository for reference while revising. + +## Other Resources + +General discussion of [Software Carpentry][swc-site], [Data Carpentry][dc-site], and [Library Carpentry][lc-site] +happens on the [discussion mailing list][discuss-list], +which everyone is welcome to join. +You can also [reach us by email][email]. + +[email]: mailto:team@carpentries.org +[dc-issues]: https://github.com/issues?q=user%3Adatacarpentry +[dc-lessons]: http://datacarpentry.org/lessons/ +[dc-site]: http://datacarpentry.org/ +[discuss-list]: https://carpentries.topicbox.com/groups/discuss +[github]: https://github.com +[github-flow]: https://guides.github.com/introduction/flow/ +[github-join]: https://github.com/join +[how-contribute]: https://app.egghead.io/playlists/how-to-contribute-to-an-open-source-project-on-github +[issues]: https://guides.github.com/features/issues/ +[swc-issues]: https://github.com/issues?q=user%3Aswcarpentry +[swc-lessons]: https://software-carpentry.org/lessons/ +[swc-site]: https://software-carpentry.org/ +[c-site]: https://carpentries.org/ +[lc-site]: https://librarycarpentry.org/ +[lc-issues]: https://github.com/issues?q=user%3Alibrarycarpentry diff --git a/README.md b/README.md new file mode 100644 index 0000000..060994a --- /dev/null +++ b/README.md @@ -0,0 +1,40 @@ +# FIXME Lesson title + +[![Create a Slack Account with us](https://img.shields.io/badge/Create_Slack_Account-The_Carpentries-071159.svg)](https://swc-slack-invite.herokuapp.com/) + +This repository generates the corresponding lesson website from [The Carpentries](https://carpentries.org/) repertoire of lessons. + +## Contributing + +We welcome all contributions to improve the lesson! Maintainers will do their best to help you if you have any +questions, concerns, or experience any difficulties along the way. + +We'd like to ask you to familiarize yourself with our [Contribution Guide](CONTRIBUTING.md) and have a look at +the [more detailed guidelines][lesson-example] on proper formatting, ways to render the lesson locally, and even +how to write new episodes. + +Please see the current list of [issues][FIXME] for ideas for contributing to this +repository. For making your contribution, we use the GitHub flow, which is +nicely explained in the chapter [Contributing to a Project](http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project) in Pro Git +by Scott Chacon. +Look for the tag ![good_first_issue](https://img.shields.io/badge/-good%20first%20issue-gold.svg). This indicates that the maintainers will welcome a pull request fixing this issue. + + +## Maintainer(s) + +Current maintainers of this lesson are + +* FIXME +* FIXME +* FIXME + + +## Authors + +A list of contributors to the lesson can be found in [AUTHORS](AUTHORS) + +## Citation + +To cite this lesson, please consult with [CITATION](CITATION) + +[lesson-example]: https://carpentries.github.io/lesson-example diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..f2ca373 --- /dev/null +++ b/_config.yml @@ -0,0 +1,120 @@ +#------------------------------------------------------------ +# Values for this lesson. +#------------------------------------------------------------ + +# Which carpentry is this ("swc", "dc", "lc", or "cp")? +# swc: Software Carpentry +# dc: Data Carpentry +# lc: Library Carpentry +# cp: Carpentries (to use for instructor traning for instance) +# incubator: Carpentries Incubator +carpentry: "swc" + +# Overall title for pages. +title: "Lesson Title" + +# Life cycle stage of the lesson +# See this page for more details: https://cdh.carpentries.org/the-lesson-life-cycle.html +# Possible values: "pre-alpha", "alpha", "beta", "stable" +# +# Lessons that are going through the transition to the +# Carpentries Workbench will go through 3 steps: +# 'transition-step-1': notice indicating a new version +# 'transition-step-2': notice encouraging to use new version +# 'transition-step-3': notice indicating the lesson is deprecated, +# with automated redirect +life_cycle: "pre-alpha" + +# For lessons in the life stages in 'transition-step-1' or later: +# - 'transition_url' holds the URL for the version of the lesson that +# uses the Workbench (needed for all 3 steps) +# - 'transition_date' (in yyyy-mm-dd format) is the date when the lesson +# will transition to being deprecated. The date only needs to be decided +# when the lesson is in 'transition-step-2'. +transition_url: +transition_date: + +#------------------------------------------------------------ +# Generic settings (should not need to change). +#------------------------------------------------------------ + +# What kind of thing is this ("workshop" or "lesson")? +kind: "lesson" + +# Magic to make URLs resolve both locally and on GitHub. +# See https://help.github.com/articles/repository-metadata-on-github-pages/. +# Please don't change it: / is correct. +repository: / + +# Email address, no mailto: +email: "team@carpentries.org" + +# Sites. +coc: "https://docs.carpentries.org/topic_folders/policies/code-of-conduct.html" +amy_site: "https://amy.carpentries.org/" +carpentries_github: "https://github.com/carpentries" +carpentries_pages: "https://carpentries.github.io" +carpentries_site: "https://carpentries.org/" +dc_site: "https://datacarpentry.org" +example_repo: "https://github.com/carpentries/lesson-example" +example_site: "https://carpentries.github.io/lesson-example" +lc_site: "https://librarycarpentry.org/" +swc_github: "https://github.com/swcarpentry" +swc_pages: "https://swcarpentry.github.io" +swc_site: "https://software-carpentry.org" +template_repo: "https://github.com/carpentries/styles" +training_site: "https://carpentries.github.io/instructor-training" +workshop_repo: "https://github.com/carpentries/workshop-template" +workshop_site: "https://carpentries.github.io/workshop-template" +cc_by_human: "https://creativecommons.org/licenses/by/4.0/" + +# Surveys. +pre_survey: "https://carpentries.typeform.com/to/wi32rS#slug=" +post_survey: "https://carpentries.typeform.com/to/UgVdRQ#slug=" +instructor_pre_survey: "https://carpentries.typeform.com/to/QVOarK#slug=" +instructor_post_survey: "https://carpentries.typeform.com/to/cjJ9UP#slug=" + +# Set to 'true' for instructor training websites only. +instructor_training: false + +# Start time in minutes (0 to be clock-independent, 540 to show a start at 09:00 am). +start_time: 0 + +# Specify that things in the episodes collection should be output. +collections: + episodes: + output: true + permalink: /:path/index.html + extras: + output: true + permalink: /:path/index.html + +# Set the default layout for things in the episodes collection. +defaults: + - values: + root: . + layout: page + - scope: + path: "" + type: episodes + values: + root: .. + layout: episode + - scope: + path: "" + type: extras + values: + root: .. + layout: page + +# Files and directories that are not to be copied. +exclude: + - Makefile + - bin/ + - .Rproj.user/ + - .vendor/ + - vendor/ + - .docker-vendor/ + +# Turn on built-in syntax highlighting. +highlighter: rouge diff --git a/_episodes/01-introduction.md b/_episodes/01-introduction.md new file mode 100644 index 0000000..2e156c2 --- /dev/null +++ b/_episodes/01-introduction.md @@ -0,0 +1,15 @@ +--- +title: "Introduction" +teaching: 0 +exercises: 0 +questions: +- "Key question (FIXME)" +objectives: +- "First learning objective. (FIXME)" +keypoints: +- "First key point. Brief Answer to questions. (FIXME)" +--- +FIXME + +{% include links.md %} + diff --git a/_extras/about.md b/_extras/about.md new file mode 100644 index 0000000..5f07f65 --- /dev/null +++ b/_extras/about.md @@ -0,0 +1,5 @@ +--- +title: About +--- +{% include carpentries.html %} +{% include links.md %} diff --git a/_extras/discuss.md b/_extras/discuss.md new file mode 100644 index 0000000..bfc33c5 --- /dev/null +++ b/_extras/discuss.md @@ -0,0 +1,6 @@ +--- +title: Discussion +--- +FIXME + +{% include links.md %} diff --git a/_extras/figures.md b/_extras/figures.md new file mode 100644 index 0000000..0012c88 --- /dev/null +++ b/_extras/figures.md @@ -0,0 +1,79 @@ +--- +title: Figures +--- + +{% include base_path.html %} +{% include manual_episode_order.html %} + + + +{% comment %} Create anchor for each one of the episodes. {% endcomment %} + +{% for lesson_episode in lesson_episodes %} + {% if site.episode_order %} + {% assign episode = site.episodes | where: "slug", lesson_episode | first %} + {% else %} + {% assign episode = lesson_episode %} + {% endif %} +
+{% endfor %} + +{% include links.md %} diff --git a/_extras/guide.md b/_extras/guide.md new file mode 100644 index 0000000..50f266f --- /dev/null +++ b/_extras/guide.md @@ -0,0 +1,6 @@ +--- +title: "Instructor Notes" +--- +FIXME + +{% include links.md %} diff --git a/index.md b/index.md new file mode 100644 index 0000000..95ccdbd --- /dev/null +++ b/index.md @@ -0,0 +1,17 @@ +--- +layout: lesson +root: . # Is the only page that doesn't follow the pattern /:path/index.html +permalink: index.html # Is the only page that doesn't follow the pattern /:path/index.html +--- +FIXME: home page introduction + + + +{% comment %} This is a comment in Liquid {% endcomment %} + +> ## Prerequisites +> +> FIXME +{: .prereq} + +{% include links.md %} diff --git a/reference.md b/reference.md new file mode 100644 index 0000000..8c82616 --- /dev/null +++ b/reference.md @@ -0,0 +1,9 @@ +--- +layout: reference +--- + +## Glossary + +FIXME + +{% include links.md %} diff --git a/setup.md b/setup.md new file mode 100644 index 0000000..b8c5032 --- /dev/null +++ b/setup.md @@ -0,0 +1,7 @@ +--- +title: Setup +--- +FIXME + + +{% include links.md %}