From 142672a263f64212d2f7608bf1ac7f8db1031d77 Mon Sep 17 00:00:00 2001 From: Greg Wilson Date: Fri, 12 Dec 2014 20:40:42 -0500 Subject: [PATCH] Including compiled HTML pages --- 01-one.html | 70 +++++++++++++ 02-two.html | 66 +++++++++++++ DESIGN.html | 64 ++++++++++++ FAQ.html | 79 +++++++++++++++ LAYOUT.html | 253 +++++++++++++++++++++++++++++++++++++++++++++++ LICENSE.html | 71 +++++++++++++ discussion.html | 48 +++++++++ index.html | 60 +++++++++++ instructors.html | 69 +++++++++++++ motivation.html | 97 ++++++++++++++++++ reference.html | 53 ++++++++++ 11 files changed, 930 insertions(+) create mode 100644 01-one.html create mode 100644 02-two.html create mode 100644 DESIGN.html create mode 100644 FAQ.html create mode 100644 LAYOUT.html create mode 100644 LICENSE.html create mode 100644 discussion.html create mode 100644 index.html create mode 100644 instructors.html create mode 100644 motivation.html create mode 100644 reference.html diff --git a/01-one.html b/01-one.html new file mode 100644 index 0000000..7e3b0f7 --- /dev/null +++ b/01-one.html @@ -0,0 +1,70 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+

Topic Title One

+
+

Learning Objectives

+
    +
  • Learning objective 1
    • +
  • Learning objective 2
    • +
+
+

Paragraphs of text --- possibly including definitions --- mixed with:

+
some code:
+    to be displayed
+
output
+from
+program
+
error reports from program (if any)
+

and possibly including:

+
+

Callout Box

+

An aside of some kind.

+
+

or an image from the figs directory:

+
+this is the image's title

this is the image's title

+
+
+

Challenge Title

+

Description of a single challenge. There may be several challenges.

+
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/02-two.html b/02-two.html new file mode 100644 index 0000000..ea737d2 --- /dev/null +++ b/02-two.html @@ -0,0 +1,66 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+

Topic Title Two

+
+

Learning Objectives

+
    +
  • Learning objective 1
    • +
  • Learning objective 2
    • +
+
+

Paragraphs of text --- possibly including definitions --- mixed with:

+
some code:
+    to be displayed
+
output
+from
+program
+
error reports from program (if any)
+

and possibly including:

+
+

Callout Box

+

An aside of some kind.

+
+
+

Challenge Title

+

Description of a single challenge. There may be several challenges.

+
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/DESIGN.html b/DESIGN.html new file mode 100644 index 0000000..50c9a85 --- /dev/null +++ b/DESIGN.html @@ -0,0 +1,64 @@ + + + + + + Software Carpentry: + + + + + + + + + + + +
+ +
+
+

+ +

Background and Design

+

There are a few things you need to know in order to understand why this template is organized the way it is:

+
    +

  1. Git uses the term clone to mean "a copy of a repository". GitHub uses the term fork to mean, "a copy of a GitHub-hosted repo that is also hosted on GitHub", and the term clone to mean "a copy of a GitHub-hosted repo that's located on someone else's machine". In both cases, the duplicate has a remote called origin that points to the original repo; other remotes can be added manually.

    2. +

  2. A user on GitHub can only have one fork of a particular repo. This is a problem for us because an author may be involved in writing several lessons, each of which has its own website repo. Those website repositories ought to be forks of this one, but since GitHub doesn't allow that, we've had to find a workaround.

    3. +

  3. If a repository has a branch called gh-pages (which stands for "GitHub pages"), then GitHub uses the HTML and Markdown files in that branch to create a website for the repository. If the repository's URL is http://github.com/darwin/finches, the URL for the website is http://darwin.github.io/finches.

    4. +

  4. We use Markdown for writing pages because it's simple to learn, and isn't tied to any specific language (the ReStructured Text format popular in the Python world, for example, is a complete unknown to R programmers). If authors want to use something else to author their lessons (e.g., IPython Notebooks), it's up to them to generate and commit Markdown formatted according to the rules below.

    +

    Note: we do not prescribe what tools instructors should use when actually teaching. The IPython Notebook, Python IDEs like Spyder, and the GOCLI (Good Ol' Command Line Interpreter) are all equally welcome up on stage --- all we specify is the format of the lesson notes.

    5. +

  5. We use Pandoc to process pages instead of Jekyll (GitHub's default conversion tool) because Pandoc supports a much richer dialect of Markdown than Jekyll. Like Jekyll, Pandoc looks for a header at the top of each page formatted like this:

    +
    ---
+variable: value
+other_variable: other_value
+---
+...stuff in the page...
    +

    and inserts the values of those variables into the page when formatting this. Lesson authors will usually not have to worry about this.

    6. +

  6. Using Pandoc instead of Jekyll means that we have to compile our Markdown into HTML on our own machines and commit it to the gh-pages branch of the lesson's GitHub repository.

    +

    It's considered bad practice to put computer-generated files under version control, but the HTML pages put into the lesson's root directory by Pandoc must be committed to version control in order for the lesson to be displayed properly on GitHub.

    +

    It's also considered bad practice to put generated files in the same directory as source files. We do it because some authors may use auxiliary source files such as R Markdown and IPython Notebook files which are executable, and contain paths to things like images and data files. If we put our source files in a sub-directory, those paths won't work (or conversely, if we put our generated files in a different directory, the paths won't work there).

    7. +

  7. In order to display properly, our generated HTML pages need artwork, CSS style files, and a few bits of Javascript. We could load these from the web, but that would make offline authoring difficult. Instead, each lesson's repository has a copy of these files, and a way of updating them (and only them) on demand.

    8. +
+

One final note: we try not to put HTML inside Markdown because it's ugly to read and write, and error-prone to process. Instead, we put things that ought to be in <div> blocks, like the learning objectives and challenge exercises, in blockquotes indented with >, and do a bit of post-processing to attach the right CSS classes to these blocks.

+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/FAQ.html b/FAQ.html new file mode 100644 index 0000000..aeff74a --- /dev/null +++ b/FAQ.html @@ -0,0 +1,79 @@ + + + + + + Software Carpentry: + + + + + + + + + + + +
+ +
+
+

+ +

FAQ

+
    +

  • Where can I get help?

    +

    Mail , or join our discussion list and ask for help there.

    • +

  • Where can I report problems or suggest improvements?

    +

    Please file an issue or .

    • +

  • Why does the lesson repository have to be created from scratch? Why not fork lesson-template on GitHub?

    +

    Because any particular user can only have one fork of a repository, but instructors frequently need to work on several workshops at once.

    • +

  • Why use Pandoc? Why not some other markup language and some other converter?

    +

    Because it supports a richer dialect of Markdown than Jekyll (the converter that GitHub uses by default). In particular, Pandoc can do tables and allows us to add styles to headings.

    • +

  • What do the labels mean?

    +
      +
    • bug: something is wrong in our tools or documentation
      • +
    • discussion: marks issues used for conversations about specific problems and questions
      • +
    • duplicate: marks an issue that was closed as redundant (include the number of the original issue in the closing comment)
      • +
    • enhancement: asks for, or adds, a new feature or new information
      • +
    • filed-by-newcomer: issue or pull request was filed by someone who is relatively new to GitHub and/or this project, and would appreciate guidance as well as feedback
      • +
    • getting-started: issue or pull request is suitable for someone new to GitHub and/or this project
      • +
    • help-wanted: a question or request for assistance
      • +
    • left-as-was: marks an issue closed because the item in question will be left as it was
      • +
    • suitable-for-newcomer: issue or pull request is a good starting point for someone who is relatively new to GitHub and/or this project
      • +
    • work-in-progress: a pull request that is not yet ready for review
      • +
    • +
+

Debugging

+

Please add notes about problems and solutions below.

+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/LAYOUT.html b/LAYOUT.html new file mode 100644 index 0000000..7f3a4b2 --- /dev/null +++ b/LAYOUT.html @@ -0,0 +1,253 @@ + + + + + + Software Carpentry: + + + + + + + + + + + +
+ +
+
+

+ +

Lesson Layout

+

Each lesson is stored in a directory laid out as described below. That directory is a self-contained Git repository (i.e., there are no submodules or clever tricks with symbolic links).

+
    +

  1. README.md: initially a copy of this file. It should be overwritten with short description of the lesson.

    2. +

  2. Other files in the root directory: the source of the lesson's web pages (and possibly auxiliary files like IPython Notebooks and R Markdown files).

    3. +

  3. code/, data/, and fig/: sub-directories containing sample code, data files, and figures. See "Code, Data, and Figures" below.

    4. +

  4. css/, img/, js/, and deck.js/: style sheets, artwork, and Javascript used in the lesson's web site. See "Support Files" below.

    5. +

  5. _layouts/ and _includes/: page templates and inclusions. See "Support Files" below.

    6. +

  6. tools/: tools for managing lessons. See "Tools" below.

    7. +
+

Code, Data, and Figures

+

All of the software samples used in the lesson must go in a directory called code/. Stand-alone data files must go in a directory called data/. Groups of related data files must be put together in a sub-directory of data/ with a meaningful (short) name. Figures, plots, and diagrams used in the lessons must go in a fig/ directory.

+

Notes:

+
    +

  1. This mirrors the layout a scientist would use for actual work. However, it may cause novice learners problems. If a program is in code/a.py, and contains a reference to a data file ../data/b.csv, then if the user runs the program from the root directory using python code/a.py, it will be unable to find the data file (since the program's working directory will be the root directory, not the data directory).

    2. +

  2. IPython Notebooks and R Markdown files, which are both code and the source for web pages, should go in the root directory. These will not be checked by our validation tool, or indexed by other tools we plan to build.

    3. +

  3. We strongly prefer SVG for line drawings, since they are smaller, scale better, and are easier to edit. Screenshots and other raster images must be PNG or JPEG format.

    4. +
+

Support Files

+

Files used to display the lesson, such as artwork, CSS, and Javascript, are stored in img/, css/, and js/ directories of their own, while the deck.js/ directory contains files used to make HTML slideshows. We keep website artwork in the img/ directory separate from figures used in the lesson (which are stored in fig/) to make it simple to update the former automatically. Most authors should not need to modify any of the support files themselves.

+

The _layouts/ directory holds the page templates used to translate Markdown to HTML, while the _includes/ directory holds snippets of HTML that are used in several page layouts. These directories have underscores at the start of their names to be consistent with Jekyll's naming conventions, but the files they contain are for Pandoc.

+

Tools

+

The tools/ directory contains tools to help create and maintain lessons:

+
    +
  • tools/check: make sure that everything is formatted properly, and print error messages identifying problems if it's not.
    • +
+

Pages

+

The root directory holds the content of the lesson, and must contain:

+
    +

  1. Makefile: contains commands to check, preview, and update the repository. Authors should not need to modify this file.

    2. +

  2. index.md: the home page for the lesson. (See "Home Page" below.)

    3. +

  3. dd-slug.md: the topics in the lesson. dd is a sequence number such as 01, 02, etc., and slug is an abbreviated single-word mnemonic for the topic. Thus, 03-filesys.md is the third topic in this lesson, and is about the filesystem. (Note that we use hyphens rather than underscores in filenames.) See "Topics" below.

    4. +

  4. motivation.md: slides for a short introductory presentation (three minutes or less) explaining what the lesson is about and why people would want to learn it. See "Introductory Slides" below.

    5. +

  5. reference.md: a cheat sheet summarizing key terms and commands, syntax, etc., that can be printed and given to learners. See "Reference Guide" below.

    6. +

  6. discussion.md: notes about more advanced ideas that would distract from the main lesson, and pointers to where to go next. See "Discussion Page" below.

    7. +

  7. instructors.md: the instructor's guide for the lesson. See "Instructor's Guide" below.

    8. +
+

Note that the lesson's title is repeated in several files. We could put this in the Makefile, and insert it into pages when compiling, but then authors would have to edit the Makefile (which we want to avoid). We could also put it in some sort of configuration file, but again, we're trying to avoid those.

+

Home Page

+

index.md must be structured as follows:

+
---
+layout: lesson
+title: Lesson Title
+---
+Paragraph(s) of introductory material.
+
+> ## Prerequisites {.prereq}
+>
+> What learners need to know before tackling this lesson.
+
+## Topics
+
+1.  [Topic Title 1](01-slug.html)
+2.  [Topic Title 2](02-slug.html)
+
+## Other Resources
+
+*   [Motivation](motivation.html)
+*   [Reference Guide](reference.html)
+*   [Next Steps](discussion.html)
+*   [Instructor's Guide](instructors.html)
+

Notes:

+
    +

  1. The description of prerequisites is prose for human consumption, not a machine-comprehensible list of dependencies. We may supplement the former with the latter once we have more experience with this lesson format and know what we actually want to do.

    2. +

  2. Software installation and configuration instructions aren't in the lesson, since they may be shared with other lessons. They will be stored centrally on the Software Carpentry web site and linked from the lessons that need them.

    3. +
+

Topics

+

Each topic page must be structured as follows:

+
---
+layout: page
+title: Lesson Title
+subtitle: Topic Title
+minutes: 10
+---
+> ## Learning Objectives
+>
+> * Learning objective 1
+> * Learning objective 2
+
+Paragraphs of text --- possibly including **definitions** ---
+mixed with:
+
+~~~ {.python}
+some code:
+    to be displayed
+~~~
+
+and:
+
+~~~ {.output}
+output
+from
+program
+~~~
+
+and:
+
+~~~ {.error}
+error reports from programs (if any)
+~~~
+
+and possibly including some of these:
+
+> ## Callout Box {.callout}
+>
+> An aside of some kind.
+
+and one or more of these:
+
+> ## Challenge Title {.challenge}
+>
+> Description of a single challenge.
+> There may be several challenges.
+

Notes:

+
    +

  1. The "expected time" heading is called minutes to encourage people to create topics that are short (10-15 minutes at most).

    2. +

  2. There are no sub-headings inside a topic other than the ones shown. (If a topic needs sub-headings, it should be broken into two or more topics.)

    3. +

  3. Every challenge should relate explicitly back to a learning objective.

    4. +

  4. Definitions of terms are marked in bold (like **this**). Nothing else should be marked as bold text --- use italics for for all other emphasis.

    5. +
+

Motivational Slides

+

Every lesson must include a short slide deck suitable for a short presentation (3 minutes or less) that the instructor can use to explain to learners how knowing the subject will help them. The slides must be laid out like this:

+
---
+layout: slides
+title: Why Make?
+---
+<section class="slide">
+## Why This Topic?
+</section>
+
+<section class="slide">
+## Some Other Point
+</section>
+

Notes:

+
    +

  1. This is the one place where we must use HTML tags in our Markdown (to delimit slides). Everything inside the section markers should be Markdown if possible.

    2. +

  2. We use deck.js for our slides as it is simpler and prettier than alternatives like reveal.js.

    3. +
+

Reference Guide

+

The reference guide is a cheat sheet for learners to print, doodle on, and take away. Its format is deliberately unconstrained for now, since we'll need to see a few before we can decide how they ought to be laid out (or whether they need to be laid out the same way at all).

+

The last section of the reference guide must be a glossary laid out as a definition list:

+
---
+layout: page
+title: Lesson Title
+subtitle: Reference
+---
+...commands and examples...
+
+## Glossary
+
+Key Word 1
+:   Definition of first term
+
+Key Word 2
+:   Definition of second term
+

Discussion Page

+

The discussion page

+
---
+layout: page
+title: Lesson Title
+subtitle: Discussion
+---
+*   First point of general discussion.
+
+    This may span several paragraphs.
+
+*   Second point of general discussion.
+

Instructor's Guide

+

Learners may go through lessons outside of class, so it seems best to keep material for instructors in a separate document, rather than interleaved in the lesson itself. Its structure is:

+
---
+layout: page
+title: Lesson Title
+subtitle: Instructor's Guide
+---
+## Legend
+
+One or more paragraphs laying out the lesson's legend (i.e., the story
+behind its running example).
+
+## Overall
+
+* Point
+
+* Point
+
+## [Topic Title 1](01-slug.html)
+
+* Point
+
+* Point
+
+1.  Discussion of first challenge.
+
+2.  Discussion of second challenge.
+
+## [Topic Title 2](02-slug.html)
+
+* Point
+
+* Point
+
+1.  Discussion of first challenge.
+
+2.  Discussion of second challenge.
+

Notes:

+
    +

  1. The topic headings must match the topic titles. (Yes, we could define these as variables in a configuration file and refer to those variables everywhere, but in this case, repetition will be a lot easier to read, and our validator can check that the titles line up.)

    2. +

  2. The points can be anything: specific ways to introduce ideas, common mistakes learners make and how to get out of them, or anything else.

    3. +

  3. Full solutions to the challenges do not have to be presented, but every challenge should be discussed, and that discussion should mention how long it typically takes to do. (Those estimates do not go in the challenge itself, since they can increase learners' stress levels.)

    4. +
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/LICENSE.html b/LICENSE.html new file mode 100644 index 0000000..1cedf05 --- /dev/null +++ b/LICENSE.html @@ -0,0 +1,71 @@ + + + + + + Software Carpentry: Licenses + + + + + + + + + + + +
+ +
+
+

Licenses

+ +

Instructional Material

+

All Software Carpentry instructional material is made available under the Creative Commons Attribution license. The following is a human-readable summary of (and not a substitute for) the full legal text of the CC BY 4.0 license.

+

You are free:

+
    +
  • to Share---copy and redistribute the material in any medium or format
    • +
  • to Adapt---remix, transform, and build upon the material
    • +
+

for any purpose, even commercially.

+

The licensor cannot revoke these freedoms as long as you follow the license terms.

+

Under the following terms:

+
    +
  • Attribution---You must give appropriate credit (mentioning that your work is derived from work that is Copyright © Software Carpentry and, where practical, linking to http://software-carpentry.org/), provide a link to the license, and indicate if changes were made. You may do so in any reasonable manner, but not in any way that suggests the licensor endorses you or your use.
    • +
+

No additional restrictions---You may not apply legal terms or technological measures that legally restrict others from doing anything the license permits. With the understanding that:

+

Notices:

+
    +
  • You do not have to comply with the license for elements of the material in the public domain or where your use is permitted by an applicable exception or limitation.
    • +
  • No warranties are given. The license may not give you all of the permissions necessary for your intended use. For example, other rights such as publicity, privacy, or moral rights may limit how you use the material.
    • +
+

Software

+

Except where otherwise noted, the example programs and other software provided by Software Carpentry are made available under the OSI-approved MIT license.

+

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

+

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

+

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

+

Other Material

+

Our code of conduct is taken from this site, and is made available under the same MIT License as our software.

+

Trademark

+

"Software Carpentry" and the Software Carpentry logo are registered trademarks of Software Carpentry, Ltd.

+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/discussion.html b/discussion.html new file mode 100644 index 0000000..16a587f --- /dev/null +++ b/discussion.html @@ -0,0 +1,48 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+

Discussion

+
    +

  • First point of general discussion.

    +

    This may span several paragraphs.

    • +

  • Second point of general discussion.

    • +
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/index.html b/index.html new file mode 100644 index 0000000..05466f4 --- /dev/null +++ b/index.html @@ -0,0 +1,60 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+ +

Paragraph of introductory material.

+
+

Prerequisites

+

A short paragraph describing what learners need to know before tackling this lesson.

+
+

Topics

+
    +
  1. Topic Title One
    2. +
  2. Topic Title Two
    3. +
+

Other Resources

+ +
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/instructors.html b/instructors.html new file mode 100644 index 0000000..5efadb7 --- /dev/null +++ b/instructors.html @@ -0,0 +1,69 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+

Instructor's Guide

+

Legend

+

One or more paragraphs laying out the lesson's legend (i.e., the story behind its running example).

+

Overall

+
    +

  • FIXME

    • +

  • FIXME

    • +
+

Topic Title One

+
    +

  • Point

    • +

  • Point

    • +

  • Be sure to describe what learners are expected to do during the topic (watch, type along, pair program, etc.)

    • +
+
    +

  1. Discussion of first challenge.

    2. +

  2. Discussion of second challenge.

    3. +
+

Topic Title Two

+
    +

  • Point

    • +

  • Point

    • +
+
    +

  1. Discussion of first challenge.

    2. +

  2. Discussion of second challenge.

    3. +
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + diff --git a/motivation.html b/motivation.html new file mode 100644 index 0000000..51c4e7f --- /dev/null +++ b/motivation.html @@ -0,0 +1,97 @@ + + + + + + + + Software Carpentry + + + + + + + + + + + + + + + + + + + + + + + + +
+ + +
+

Why Topic?

+
+
+

More Explanation

+
    +
  • With
    • +
  • Bullet
    • +
  • Points
    • +
+
+
+

Next Steps

+Here we go! +
+ + + + + +
+ ← + → +
+ + +

+ + / + +

+ + +
+ + + + +
+ + +
+ + + + + + + + + + + + + + + + diff --git a/reference.html b/reference.html new file mode 100644 index 0000000..7d70e2c --- /dev/null +++ b/reference.html @@ -0,0 +1,53 @@ + + + + + + Software Carpentry: Lesson Title + + + + + + + + + + + +
+ +
+
+

Lesson Title

+

Reference

+

...commands and examples...

+

Glossary

+
+
Key Word 1
+
Definition of first term +
+
Key Word 2
+
Definition of second term +
+
+
+
+
+ Email + GitHub + License + Bug Report +
+
+ + + + + -- GitLab