Skip to content
This repository has been archived by the owner on Jan 3, 2018. It is now read-only.

Commit

Permalink
Merge pull request #543 from stevenkoenig/readme-and-contributing-cha…
Browse files Browse the repository at this point in the history 
…nges

Readme and contributing changes
  • Loading branch information
Greg Wilson committed Jun 18, 2014
2 parents 1fefc1e + 800a86e commit 3bac198
Show file tree
Hide file tree
Showing 2 changed files with 62 additions and 48 deletions.
79 changes: 46 additions & 33 deletions CONTRIBUTING.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,25 @@ to get feedback on your ideas and coordinate with other developers.

**Table of Contents**

* [Working With GitHub](#working-with-github)
* [Locations and Formats](#locations-and-formats)
* [Working With GitHub](#working-with-github)
* [Locations](#locations)
* [Formats](#formats)
* [Sample Files](#sample-files)
* [Previewing](#previewing)
* [FAQ](#faq)

Working With GitHub
-------------------

In general, we are using Git and GitHub for almost everything.
But if it is easier for you to send your contributions to us some other way,
please mail us at
[admin@software-carpentry.org](mailto:admin@software-carpentry.org).
Given a choice between you creating content or wrestling with Git,
we'd rather have you doing the former.

The GitHub workflow looks like this:

1. Fork the `swcarpentry/bc` repository on GitHub.

2. Clone that repository to your own machine.
Expand All @@ -41,14 +51,8 @@ Working With GitHub

5. Send a pull request to the `master` branch of `[swcarpentry/bc](http://github.com/swcarpentry/bc)`.

If it is easier for you to send them to us some other way,
please mail us at
[admin@software-carpentry.org](mailto:admin@software-carpentry.org).
Given a choice between you creating content or wrestling with Git,
we'd rather have you doing the former.

Locations and Formats
---------------------
Locations
---------

Every subject has a sub-directory of its own,
while individual topics are files in that directory.
Expand All @@ -61,25 +65,30 @@ and so on.
(We use two digits followed by a one-word topic key
to ensure files appear in the right order when listed.)

Lessons may be written in Markdown,
as IPython Notebooks,
or in other formats.
However,
as explained in [the README file](README.md),
Jekyll (the tool GitHub uses to create websites)
only knows how to handle Markdown and HTML.
if some other format is used,
the author of the lesson must
add the generated Markdown to the repository.
This ensures that people who *aren't* familiar with some format
don't have to install the tools needed to work with it
(e.g.,
R programmers don't have to install the IPython Notebook).

> If a lesson is in a format we don't already handle,
> the author must also add something to the Makefile
> to re-create the Markdown from the source.
> Please check with us if you plan to do this.
Formats
-------

We are using [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
to convert lessons in [Markdown](https://en.wikipedia.org/wiki/Markdown)
to [HTML](https://en.wikipedia.org/wiki/HTML).
Therefore, we require every lesson to be available in Markdown.
But this does not mean that you have to write it in Markdown as well.

The following list contains more detailed instructions for different formats:

* Markdown: Nothing to do.
* IPython Notebook: Generate and provide a Markdown version in addition
to the IPython Notebook.
Look at our existing files to get an idea how the IPython Notebook
should look like.
* Other formats: Generate and provide a Markdown version in addition
to the file in the original format.
In order to be able to recreate the Markdown from source,
include the conversion from this other format to Markdown
in the `Makefile` as well. This ensures that people who *aren't* familiar
with some format don't have to install the tools needed to work with it
(e.g., R programmers don't have to install the IPython Notebook).
**Please check with us if you plan to do this.**

Sample Files
------------
Expand All @@ -104,26 +113,30 @@ run the command `make site`.
This runs Jekyll with the same flags that GitHub uses when things are committed to the `gh-pages` branch.
Jekyll's output is stored in a directory called `_site`.

Other useful commands in the main Makefile are:
Other useful commands in the main `Makefile` are:

* `make commands` (or just `make` on its own): list available commands.
* `make check`: check that the repository's `index.html` file is properly formatted.
* `make clean`: remove editor backup files and the `_site` directory.
* `make fixme`: list uses of the word `FIXME` in source files.

The commands to convert IPython Notebooks to Markdown
are stored in a separate Makefile called `ipynb.mk`
are stored in a separate `Makefile` called `ipynb.mk`
to simplify maintenance
and ensure that the main Makefile only does what Jekyll on GitHub will do.
and ensure that the main `Makefile` only does what Jekyll on GitHub will do.
To re-do conversion of notebooks to Markdown files,
use `make ipynb`.

FAQ
---

* *Where can I get help?*
<br/>
Mail us at [admin@software-carpentry.org](mailto:admin@software-carpentry.org),
come chat with us on [our IRC channel](irc://moznet/sciencelab),
or join our [discussion list](http://software-carpentry.org/pages/discuss.html)
and ask for help there.
* *Is there a list of open issues to tackle?*
The [open issues for the bc repository](https://github.com/swcarpentry/bc/issues)
and also the [related projects](http://www.software-carpentry.org/pages/create.html#related)
listed on the create page are a good starting point.

31 changes: 16 additions & 15 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ The sections below explain:

* how GitHub turns a repository into a web site,
* how you can build a website for your bootcamp using this repo as a starting point,
* what lessons we have,
* which lessons we have,
* where they're located, and
* how to add new lessons.

Expand All @@ -32,14 +32,14 @@ You should not try to use the same repo for both purposes because:

**Table of Contents**

* [Background](#background)
* [Getting Started](#getting-started)
* [Previewing the Site](#previewing-the-site)
* [Variables](#variables)
* [Website Content](#website-content)
* [Lesson Material](#lesson-material)
* [Building Things](#building-things)
* [Site Map](#site-map)
* [Background](#background)
* [Getting Started](#getting-started)
* [Previewing the Site](#previewing-the-site)
* [Variables](#variables)
* [Website Content](#website-content)
* [Lesson Material](#lesson-material)
* [Building Things](#building-things)
* [Site Map](#site-map)
* [FAQ](#faq)

Background
Expand Down Expand Up @@ -93,15 +93,15 @@ rather than Git itself.

then GitHub doesn't just copy the file over verbatim.
Instead,
it runs the file through a translator called Jekyll
it runs the file through a translator called [Jekyll](https://en.wikipedia.org/wiki/Jekyll_%28software%29)
that looks for specially-formatted commands embedded in the file.

6. Commands can be embedded in the body of a page.
One is `{% include somefile.html %}`,
which tells Jekyll to copy the contents of `somefile.html` into the file being translated;
this is used to create standard headers and footers for pages.
Another is `{{variable}}`:
when Jekyll see this,
when Jekyll sees this,
it replaces it with the value of `variable`.
This is used to insert things like a contact email address and the URL for our Twitter account.

Expand Down Expand Up @@ -370,7 +370,7 @@ Lesson Material
in directories under `intermediate`.
3. Our old lesson material
is in the `lessons` directory.
We plan to retire it in Spring 2014,
We plan to retire it in Spring 2014.

As explained [below](#building-things),
you can use `make` to compile this material in the way that GitHub does
Expand Down Expand Up @@ -422,7 +422,7 @@ The most important files and directories are **highlighted**.
* _layouts/ - Jekyll page layouts.
* **_site/** - output directory (created when building the site locally).
* _templates/ - template files for conversion of IPython Notebooks to Markdown.
Templates for other conversion systems (e.g., Pandoc) should go here too.
Templates for other conversion systems (e.g., Pandoc) should go here, too.
* bib.md - bibliography.
* bin/ - miscellaneous tools used in building the site.
* book.md - generated when compiling the website locally.
Expand Down Expand Up @@ -503,7 +503,7 @@ FAQ
Uninstall pygments.rb 0.5.1 or 0.5.2, install 0.5.0. For example, here's how you would
uninstall pygments 0.5.2 and restore version 0.5.0:

~~~
~~~
$ gem uninstall pygments.rb --version "=0.5.2"
$ gem install pygments.rb --version "=0.5.0"
~~~
Expand All @@ -512,7 +512,7 @@ FAQ
<br/>
The output of `make check` looks like this:

~~~
~~~
WARNING: Unrecognized alias: 'output', it will probably have no effect.[TerminalIPythonApp] File not found: u'nbconvert'
cp tmp/python/novice/01-numpy.html _site/python/novice/01-numpy.html
cp: cannot stat ‘tmp/python/novice/01-numpy.html’: No such file or directory
Expand Down Expand Up @@ -543,3 +543,4 @@ FAQ
<br/>
Use subdirectories like `2013-07-01-esu/beginners`,
so that main directory names always follow our four-part convention.

0 comments on commit 3bac198

Please sign in to comment.