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 #513 from gvwilson/creating-web-data-lesson
Browse files Browse the repository at this point in the history 
Creating a lesson on syndicating web data
  • Loading branch information
Greg Wilson committed Oct 1, 2014
2 parents aee54f9 + 7d92cf0 commit 0ddb4b6
Show file tree
Hide file tree
Showing 24 changed files with 1,880 additions and 214 deletions.
92 changes: 55 additions & 37 deletions CONTRIBUTING.md
View file
Expand Up @@ -22,8 +22,9 @@ and then open an issue of your own to get feedback on your ideas and coordinate

* [Topic Maintainers](#topic-maintainers)
* [Working With GitHub](#working-with-github)
* [Locations](#locations)
* [Formats](#formats)
* [Previewing](#previewing)
* [Locations and Formats](#locations-and-formats)
* [Sample Files](#sample-files)
* [Labels](#labels)
* [FAQ](#faq)
Expand Down Expand Up @@ -55,6 +56,15 @@ the topic name links to that repository.
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 @@ -74,6 +84,45 @@ please mail us at
Given a choice between you creating content or wrestling with Git,
we'd rather have you doing the former.

Locations
---------

Every subject has a sub-directory of its own,
while individual topics are files in that directory.
For example,
the `novice/git` directory holding our introduction to Git for newcomers
contains the files
`00-intro.md`,
`01-backup.md`,
and so on.
(We use two digits followed by a one-word topic key
to ensure files appear in the right order when listed.)

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.**

Previewing
----------

Expand All @@ -82,7 +131,6 @@ run the command `make site`.
This runs Jekyll with the same flags that GitHub uses when things are committed to the `gh-pages` branch
and puts the results in a directory called `_site`.


You should also run `make check` before pushing changes to your `index.html` home page
to your repository.
If you don't have Make installed,
Expand All @@ -109,40 +157,6 @@ 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`.

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

Every subject has a sub-directory of its own,
while individual topics are files in that directory.
For example,
the `novice/git` directory holding our introduction to Git for newcomers
contains the files
`00-intro.md`,
`01-backup.md`,
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.
Sample Files
------------

Expand Down Expand Up @@ -188,11 +202,15 @@ 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.

[windows-installer]: https://github.com/swcarpentry/windows-installer
[installation-test]: http://git.tremily.us/?p=swc-setup-installation-test.git
1 change: 1 addition & 0 deletions Makefile
View file
Expand Up @@ -72,6 +72,7 @@ ALL_SRC = \
$(wildcard intermediate/regex/*.md) \
$(wildcard intermediate/python/*.md) \
$(wildcard intermediate/doit/*.md) \
$(wildcard intermediate/webdata/*.md) \
$(wildcard slides/*.html) \
$(MOST_SRC)

Expand Down
28 changes: 14 additions & 14 deletions README.md
View file
Expand Up @@ -47,14 +47,14 @@ and so on.

**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 @@ -108,15 +108,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 {% raw %}{% include something.html %}{% endraw %},
which tells Jekyll to copy the contents of `something.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 @@ -403,7 +403,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 @@ -455,7 +455,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 @@ -535,7 +535,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 @@ -544,7 +544,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

0 comments on commit 0ddb4b6

Please sign in to comment.