Skip to content
README.md 2.26 KiB
Newer Older
Greg Wilson's avatar
Greg Wilson committed

Greg Wilson's avatar
Greg Wilson committed
This repository shows how to create a lesson using
the [Software Carpentry lesson template][swc-lesson-template],
Greg Wilson's avatar
Greg Wilson committed
and is itself an example of the use of that template.
Greg Wilson's avatar
Greg Wilson committed

1.  Do *not* fork this repository directly on GitHub.
Greg Wilson's avatar
Greg Wilson committed
    Instead, please follow the instructions in [the setup instructions][setup]
Greg Wilson's avatar
Greg Wilson committed
    to create a repository for your lesson from
Greg Wilson's avatar
Greg Wilson committed
    [the template repository][styles].
Greg Wilson's avatar
Greg Wilson committed

2.  Once you have created the repository,
Greg Wilson's avatar
Greg Wilson committed
    please go through [the episodes][rendered] to format your lesson.
Greg Wilson's avatar
Greg Wilson committed
3.  Please keep the master copy of your lesson in your repository's `gh-pages` branch,
    since that is what is
Greg Wilson's avatar
Greg Wilson committed
    [automatically published as a website by GitHub][github-pages].
Greg Wilson's avatar
Greg Wilson committed
    To simplify reviewing,
    please make changes in feature branches
Greg Wilson's avatar
Greg Wilson committed
    and then submit pull requests against the `gh-pages` branch
    of your lesson's repository.
Greg Wilson's avatar
Greg Wilson committed
The layout of this repository is explained in [this site's episodes][rendered].
In brief:
1.  The source for pages that appear as direct items in the navigation bar
    are stored in the root directory.
2.  Source files for lesson episodes are stored in `_episodes`
    so that we can make use of [Jekyll collections][collections];
    `_episodes/01-xyz.md` generates `/01-xyz/index.html`,
    which can be linked to using `/01-xyz/`.
3.  Files that appear under the "extras" menu pulldown are stored in `_extras`.
4.  Figures and other files are stored in the `files` directory,
    while data sets are stored in `data`
    and source code for examples in `code`.
Greg Wilson's avatar
Greg Wilson committed
1.  Run `bin/lesson_initialize.py` to create files
Greg Wilson's avatar
Greg Wilson committed
    that can't be stored in the template repository
    (because they would cause repeated merge conflicts),
Greg Wilson's avatar
Greg Wilson committed
    then edit `_config.yml` as described in the episode on organization.
Greg Wilson's avatar
Greg Wilson committed
2.  For a list of helpful commands run `make` in this directory.
    If you are looking for things to work on,
    please see [the list of issues for this repository][issues].

[collections]: https://jekyllrb.com/docs/collections/
Greg Wilson's avatar
Greg Wilson committed
[github-pages]:(https://help.github.com/articles/creating-project-pages-manually/
[issues]: https://github.com/swcarpentry/lesson-example/issues/
[rendered]: https://swcarpentry.github.io/lesson-example/
Greg Wilson's avatar
Greg Wilson committed
[setup]: setup.md
[styles]: https://github.com/swcarpentry/styles/