From 8b2c9c638ca4f244fc87c9cef45de64148550dbe Mon Sep 17 00:00:00 2001 From: "Steven Koenig (Kreuvf)" Date: Sun, 15 Jun 2014 18:39:28 +0200 Subject: [PATCH 1/4] * Add small changes to README.md --- README.md | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 19b6940a6..0f364c2ca 100644 --- a/README.md +++ b/README.md @@ -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. @@ -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 @@ -93,7 +93,7 @@ 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. @@ -101,7 +101,7 @@ rather than Git itself. 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. @@ -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 @@ -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. @@ -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" ~~~ @@ -512,7 +512,7 @@ FAQ
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 @@ -543,3 +543,4 @@ FAQ
Use subdirectories like `2013-07-01-esu/beginners`, so that main directory names always follow our four-part convention. + From 8b7e43449cb68d39165fcb9b9deac7611e2d91f2 Mon Sep 17 00:00:00 2001 From: "Steven Koenig (Kreuvf)" Date: Sun, 15 Jun 2014 18:42:35 +0200 Subject: [PATCH 2/4] * Add clarifications to CONTRIBUTING.md * Split 'Locations and Formats' * Rewrite 'Formats' paragraph --- CONTRIBUTING.md | 71 ++++++++++++++++++++++++++++++------------------- 1 file changed, 43 insertions(+), 28 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ff3e4a76a..9bda22dbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -19,8 +19,9 @@ 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) @@ -28,6 +29,15 @@ to get feedback on your ideas and coordinate with other developers. 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. @@ -41,14 +51,9 @@ 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. @@ -61,25 +66,29 @@ 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 ------------ @@ -127,3 +136,9 @@ FAQ 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. + From 4170062a5a157ff73cf85fb6d5fe5d2a22934ccc Mon Sep 17 00:00:00 2001 From: "Steven Koenig (Kreuvf)" Date: Sun, 15 Jun 2014 18:31:45 +0200 Subject: [PATCH 3/4] * Remove superfluous newline --- CONTRIBUTING.md | 1 - 1 file changed, 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9bda22dbd..e81abfb62 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,7 +51,6 @@ The GitHub workflow looks like this: 5. Send a pull request to the `master` branch of `[swcarpentry/bc](http://github.com/swcarpentry/bc)`. - Locations --------- From 800a86e0098db95892c775a0854563d7c6e52a5f Mon Sep 17 00:00:00 2001 From: "Steven Koenig (Kreuvf)" Date: Tue, 17 Jun 2014 20:55:50 +0200 Subject: [PATCH 4/4] * Remove superfluous
s * Make the word 'Makefile' stand out * Fix Markdown mark-up --- CONTRIBUTING.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e81abfb62..7ed607c96 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -75,6 +75,7 @@ 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. @@ -84,7 +85,7 @@ The following list contains more detailed instructions for different formats: 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 + 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.** @@ -112,7 +113,7 @@ 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. @@ -120,9 +121,9 @@ Other useful commands in the main Makefile are: * `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`. @@ -130,13 +131,11 @@ FAQ --- * *Where can I get help?* -
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.