X-Git-Url: https://git.arvados.org/rnaseq-cwl-training.git/blobdiff_plain/9c447b8e6ca87637b4ada4a6361c56d06cd8f0f8..e0ade1114622810ee1d4fb8b9a8f00c9fb5dc699:/bin/lesson_initialize.py diff --git a/bin/lesson_initialize.py b/bin/lesson_initialize.py index cfd8f6f..acb253b 100755 --- a/bin/lesson_initialize.py +++ b/bin/lesson_initialize.py @@ -3,10 +3,10 @@ """Initialize a newly-created repository.""" +from __future__ import print_function import sys import os - ROOT_AUTHORS = '''\ FIXME: list authors' names and email addresses. ''' @@ -45,7 +45,7 @@ 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][contact]. + 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. @@ -61,16 +61,37 @@ and to meet some of our community members. you can submit a pull request (PR). Instructions for doing this are [included below](#using-github). -## What We're Looking For +## 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 and submitting [bug reports][issues] about things that don't work, aren't clear, or are missing. -If you are looking for ideas, -please see [the list of issues for this repository][issues], -or the issues for [Data Carpentry][dc-issues] +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] and [Software Carpentry][swc-issues] projects. Comments on issues and reviews of pull requests are just as welcome: @@ -80,7 +101,7 @@ it's 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 We're *Not* Looking For +## 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. @@ -96,69 +117,53 @@ Our workshops typically contain a mixture of Windows, Mac OS X, and Linux users; in order to be usable, our lessons must run equally well on all three. -## Getting Started - -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. +## Using GitHub -If you want to start adding or fixing material yourself, -you may want to look at +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]. -In brief: - -1. The published copy of the lesson is in the `gh-pages` branch of the repository - (so that GitHub will regenerate it automatically). - Please create all branches from that, - and merge the [master repository][repo]'s `gh-pages` branch into your `gh-pages` branch - before starting work. - Please do *not* work directly in your `gh-pages` branch, - since that will make it difficult for you to work on other contributions. - -2. We use [GitHub flow][github-flow] to manage changes: - 1. Create a new branch in your desktop copy of this repository for each significant change. - 2. Commit the change in that branch. - 3. Push that branch to your fork of this repository on GitHub. - 4. Submit a pull request from that branch to the [master repository][repo]. - 5. If you receive feedback, - make changes on your desktop and push to your branch on GitHub: - the pull request will update automatically. - -Each lesson has 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. - -## Our Template - -[This documentation][example-site] explains how we format our lessons -(and is itself an example of that formatting). +To manage changes, we follow [GitHub flow][github-flow]. +Each lesson has 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 master 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 master 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 master `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 master `gh-pages` branch. +Lastly, published copies of all the lessons are available in the `gh-pages` branch of the master +repository for reference while revising. ## Other Resources General discussion of [Software Carpentry][swc-site] and [Data Carpentry][dc-site] happens on the [discussion mailing list][discuss-list], which everyone is welcome to join. -You can also [reach us by email][contact]. +You can also [reach us by email][email]. -[contact]: mailto:admin@software-carpentry.org +[email]: mailto:admin@software-carpentry.org [dc-issues]: https://github.com/issues?q=user%3Adatacarpentry [dc-lessons]: http://datacarpentry.org/lessons/ [dc-site]: http://datacarpentry.org/ [discuss-list]: http://lists.software-carpentry.org/listinfo/discuss -[example-site]: https://swcarpentry.github.io/lesson-example/ -[github]: http://github.com +[github]: https://github.com [github-flow]: https://guides.github.com/introduction/flow/ [github-join]: https://github.com/join [how-contribute]: https://egghead.io/series/how-to-contribute-to-an-open-source-project-on-github -[issues]: https://github.com/{USERNAME}/{LESSON-NAME}/issues/ -[repo]: https://github.com/{USERNAME}/{LESSON-NAME}/ +[issues]: https://guides.github.com/features/issues/ [swc-issues]: https://github.com/issues?q=user%3Aswcarpentry -[swc-lessons]: http://software-carpentry.org/lessons/ -[swc-site]: http://software-carpentry.org/ +[swc-lessons]: https://software-carpentry.org/lessons/ +[swc-site]: https://software-carpentry.org/ ''' ROOT_CONFIG_YML = '''\ @@ -166,59 +171,63 @@ ROOT_CONFIG_YML = '''\ # Values for this lesson. #------------------------------------------------------------ -# Which carpentry is this ("swc" or "dc")? +# Which carpentry is this ("swc", "dc", or "lc")? carpentry: "swc" -# What kind of thing is this ("workshop" or "lesson")? -kind: "lesson" - # Overall title for pages. title: "Lesson Title" -# Account (without slashes). -account: "[[USER-NAME]]" - -# Root URL below account (without slashes). -project: "[[REPO-NAME]]" - -# Contact email address. -email: "[[CONTACT-ADDRESS]]" +# Contact. This *must* include the protocol: if it's an email +# address, it must look like "mailto:lessons@software-carpentry.org", +# or if it's a URL, "https://gitter.im/username/ProjectName". +email: "mailto:lessons@software-carpentry.org" #------------------------------------------------------------ # Generic settings (should not need to change). #------------------------------------------------------------ -# Is this production or development? (Overridden in _config_dev.yml.) -is_production: true +# 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/. +repository: / # Sites. amy_site: "https://amy.software-carpentry.org/workshops" -dc_site: "https://datacarpentry.org" +dc_site: "http://datacarpentry.org" swc_github: "https://github.com/swcarpentry" swc_site: "https://software-carpentry.org" +swc_pages: "https://swcarpentry.github.io" +lc_site: "https://librarycarpentry.github.io/" template_repo: "https://github.com/swcarpentry/styles" example_repo: "https://github.com/swcarpentry/lesson-example" example_site: "https://swcarpentry.github.com/lesson-example" workshop_repo: "https://github.com/swcarpentry/workshop-template" workshop_site: "https://swcarpentry.github.io/workshop-template" +training_site: "https://swcarpentry.github.io/instructor-training" # Surveys. pre_survey: "https://www.surveymonkey.com/r/swc_pre_workshop_v1?workshop_id=" post_survey: "https://www.surveymonkey.com/r/swc_post_workshop_v1?workshop_id=" +training_post_survey: "https://www.surveymonkey.com/r/post-instructor-training" -# Start time in minutes (540 is 09:00 am) -start_time: 540 +# 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/ + permalink: /:path/index.html extras: output: true + permalink: /:path/index.html # Set the default layout for things in the episodes collection. defaults: + - values: + root: .. - scope: path: "" type: episodes @@ -230,13 +239,15 @@ exclude: - Makefile - bin -# Turn off built-in syntax highlighting. -highlighter: false +# Turn on built-in syntax highlighting. +highlighter: rouge ''' ROOT_INDEX_MD = '''\ --- layout: lesson +root: . +permalink: index.html # Is the only page that don't follow the partner /:path/index.html --- FIXME: home page introduction @@ -249,6 +260,7 @@ FIXME: home page introduction ROOT_REFERENCE_MD = '''\ --- layout: reference +root: . --- ## Glossary @@ -260,11 +272,50 @@ ROOT_SETUP_MD = '''\ --- layout: page title: Setup -permalink: /setup/ +root: . --- FIXME ''' +ROOT_AIO_MD = '''\ +--- +layout: page +root: . +--- + +{% comment %} +Create anchor for each one of the episodes. +{% endcomment %} +{% for episode in site.episodes %} +
+{% endfor %} +''' + EPISODES_INTRODUCTION_MD = '''\ --- title: "Introduction" @@ -283,7 +334,6 @@ EXTRAS_ABOUT_MD = '''\ --- layout: page title: About -permalink: /about/ --- {% include carpentries.html %} ''' @@ -292,7 +342,6 @@ EXTRAS_DISCUSS_MD = '''\ --- layout: page title: Discussion -permalink: /discuss/ --- FIXME ''' @@ -301,16 +350,48 @@ EXTRAS_FIGURES_MD = '''\ --- layout: page title: Figures -permalink: /figures/ --- -{% include all_figures.html %} + +{% comment %} +Create anchor for each one of the episodes. +{% endcomment %} +{% for episode in site.episodes %} +
+{% endfor %} ''' EXTRAS_GUIDE_MD = '''\ --- layout: page -title: "Instructors' Guide" -permalink: /guide/ +title: "Instructor Notes" --- FIXME ''' @@ -323,11 +404,12 @@ BOILERPLATE = ( ('index.md', ROOT_INDEX_MD), ('reference.md', ROOT_REFERENCE_MD), ('setup.md', ROOT_SETUP_MD), + ('aio.md', ROOT_AIO_MD), ('_episodes/01-introduction.md', EPISODES_INTRODUCTION_MD), ('_extras/about.md', EXTRAS_ABOUT_MD), ('_extras/discuss.md', EXTRAS_DISCUSS_MD), ('_extras/figures.md', EXTRAS_FIGURES_MD), - ('_extras/guide.md', EXTRAS_GUIDE_MD) + ('_extras/guide.md', EXTRAS_GUIDE_MD), )