Merge branch 'namespaced' of git://tremily.us/swc-setup-installation-test into assembled

Merge branch 'namespaced' of git://tremily.us/swc-setup-windows-installer into assembled

Merge branch 'namespaced' of git://tremily.us/swc-setup-get-my-ip into assembled

Merge branch 'namespaced' of git://tremily.us/swc-setup into assembled

Merge branch 'master' into assembled

This is a no-op merge, explicitly considering and rejecting the
submodules from the master branch.  After this merge, future merges
from the master branch will pick up any content changes.

  $ git merge --log --no-ff --strategy ours master

* master:
  setup: Add a submodule with student-setup utilities
  version-control: Add a submodule with my subject-level notes

README.md: Add nesting setup/installation-test/

Mimic the path that submodule users will have.

swc-windows-installer.py: Add nesting setup/windows-installer/

Mimic the path that submodule users will have.

get-my-ip.py: Add nesting setup/get-my-ip/

Mimic the path that submodule users will have.

setup: Add a submodule with student-setup utilities

Merge branch 'master' into namespaced

This is a no-op merge, explicitly considering and rejecting the
submodules from the master branch.  After this merge, future merges
from the master branch will pick up any content changes.

* master:
  installation-test: Add a submodule with my installation test scripts
  windows-installer: Add a submodule with Ethan's Windows installer
  get-my-ip: Add a submodule with my IP detection script

README.md: Add nesting setup/

This gives the submodule-averse the nesting they'd usually get by
merging the master branch in a submodule at setup/.  They'll have to
merge the submodule's 'namespaced' branches by hand to pull in the
equivalent content.

installation-test: Add a submodule with my installation test scripts

windows-installer: Add a submodule with Ethan's Windows installer

get-my-ip: Add a submodule with my IP detection script

Merge branch 'master' into namespaced

This is a no-op merge, explicitly considering and rejecting the
de-namespacing from the master branch.  After this merge, future
merges from the master branch will pick up any content changes.

  $ git merge --log --no-ff --strategy ours master

* master:
  README.md: Remove nesting setup/

README.md: Remove nesting setup/

There's no need to hard-code target directories in this repository.
Anyone consuming this material can use submodules and pick their own
target directory.

README: Summarize the purpose of this repository

Merge branch 'master' into namespaced

This is a no-op merge, explicitly considering and rejecting the
de-namespacing from the master branch.  After this merge, future
merges from the master branch will pick up any content changes.

  $ git merge --log --no-ff --strategy ours master

* master:
  swc-windows-installer.py: Remove nesting setup/

swc-windows-installer.py: Remove nesting setup/

There's no need to hard-code target directories in this repository.
Anyone consuming this material can use submodules and pick their own
target directory.

Merge branch 'master' into namespaced

This is a no-op merge, explicitly considering and rejecting the
de-namespacing from the master branch.  After this merge, future
merges from the master branch will pick up any content changes.

  $ git merge --log --no-ff --strategy ours master

* master:
  get-my-ip.py: Remove nesting setup/

get-my-ip.py: Remove nesting setup/

There's no need to hard-code target directories in this repository.
Anyone consuming this material can use submodules and pick their own
target directory.

version-control: Add a submodule with my subject-level notes

instructor.md: Move README.md to instructor.md

This is instructor-facing content.  We still need an inspirational
blurb for the student-facing README.

Conversion of all rst to corresponding markdown files

We use git-flavoured markdown

.mailmap: standardize identifiers for Joshua, Katy, Matt, and Sri

Ignore weird mac DS_Store files.

Update LICENSE.md

Added CC license.
Removed cruft.

README.md: Line wrapping and reference-style links

This makes the README easier to read in a terminal or editor, while
leaving the Markdown output unchanged.

Adding contributing guidelines.

Includes license, workflow, and file formats sections.

Adding some useful developer info and links to the README.

Signed-off-by: Matt Davis <jiffyclub@gmail.com>

.mailmap: Standardize identifiers for Lynne and Matt

swc-nano-installer.py: Remove now that changes are in swc-windows-installer.py

swc-windows-installer.py: Rework install paths to use ~/.swc

Instead of cluttering the user's home directory with multiple
SWC-installed directories, reduce clutter and improve namespacing by
dumping everything inside ~/.swc.  Think of it as a SWC-specific
~/.local.  We avoid actually using ~/.local because users might
already be using that for other purposes.

Use os.makedirs to create the nano install directory if it does not
already exist, because ZipFile.extract uses os.mkdir internally, and
mkdir will not recursively create directories.

swc-windows-installer.py: Remove IPython and nose entry points

Ethan thought these had been fixed upstream, and Aron Ahmadia pointed
to the Anaconda v1.6.2 release notes [1]:

  2013-07-09: 1.6.2: (Windows only)

    Fixed path being incorrectly appended on Windows during install

That means we can drop our entry point scripts and fall back to just
installing Nano and setting up EDITOR.

[1]: http://docs.continuum.io/anaconda/changelog.html

swc-windows-installer.py: De-emphasize Anaconda

Bridge the gap between the original Anaconda plug and Ethan's simpler
"Install Python" from 833d0ee (Add a Nano installer for Windows,
2013-09-17).  As of Anaconda 1.7.0, IPython 1.0.0 and nose 1.3.0 are
included by default [1].

[1]: http://docs.continuum.io/anaconda/pkgs.html

swc-windows-installer.py: Rework paths in main()

Based on Ethan's path handling in 833d0ee (Add a Nano installer for
Windows, 2013-09-17), while still retaining the entry-point creation
for IPython and nose.

swc-windows-installer.py: Generalize update_bash_profile

And rename from make_bash_profile now that we're appending instead of
creating (since c5d5414, Append exports to end of .bash_profile
instead of overwriting, 2013-09-19).

This more general form can be used to add even more paths, for example
our IPython and nosetest entry points.

swc-windows-installer.py: Bring in Ethan's make_bash_profile and make_posix_path

This integerates some of Ethan's nano-installer changes.  In the pull
request, Ethan elaborates on the .bash_profile choice [1]:

  In response to comments on the Tutors list the installer now uses
  .bash_profile instead of .bashrc and appends the lines rather than
  overwriting the file. I have also added comments that indicate where
  the new lines in .bash_profile come from.

  Once the Python version is in I'll move on to getting this compiled
  into a .exe file, which should be more familiar to our students and
  won't run into issues with Canopy installs opening the file in
  Canopy rather than executing it.

The referenced tutors@ discussion is in the messages leading up to
[2], where Ethan top-quotes a discussion with R. David Murray about
the relative merits of .bash_profile and .bashrc.  The imporant point
David made was that .bash_profile is only executed once at login,
while .bashrc is executed for each new shell.  Putting PATH appends in
.bash_profile means that you don't end up adding duplicate entries to
the PATH as you spawn subshells.  For example:

  ${ORIGINAL_PATH}:${NANO_PATH}:${NANO_PATH}:...

[1]: https://github.com/swcarpentry/bc/pull/35
[2]: http://lists.software-carpentry.org/pipermail/tutors_lists.software-carpentry.org/2013-September/000969.html

Merge branch 'nano-installer' into windows-installer

* nano-installer:
  Remove testing line
  Append exports to end of .bash_profile instead of overwriting
  Switch from using .bashrc to .bash_profile nano path and editor export
  Add a Nano installer for Windows

Remove testing line

Append exports to end of .bash_profile instead of overwriting

In the process at an explanation of where the lines came from
so that users know they can remove the lines if desired.

Switch from using .bashrc to .bash_profile nano path and editor export

Add a Nano installer for Windows

1. Downloads and installs Nano into the users home directory
2. Adds Nano to the path
3. Makes Nano the default editor

swc-installation-test-2.py: added support for py.test

swc-windows-installer.py: Use the stdlib's urlopen()

This way I can test the script (on Linux, but whatever) without having
to install an additional package.

swc-windows-installer.py: Use lists for file content

This allows us to keep the usual Python block indentation while still
producing the appropriate wrapper content.

swc-windows-installer.py: Use `with` to write script wrappers

From PEP 343.  This gives you automatic file descriptor (file handles
on Windows?) cleanup on errors.  Also use os.path.join() to build the
paths.

[1]: http://www.python.org/dev/peps/pep-0343/

swc-windows-installer.py: Simplify `ipython` wrapper

This matches my system's `/usr/bin/ipython-2.7`, and is the hook
defined in IPython's setupbase.py:

  'ipython%s = IPython.frontend.terminal.ipapp:launch_new_instance'

This should handle the 'notebook' option internally.

swc-windows-installer.py: Extract nano directly to the install directory

This is more efficient than "extract to . and then copy".  I also
renamed the install_nano() argument.  The function doesn't care that
we're currently passing the Python script directory; it will work
perfectly well with a different directory in the PATH.

swc-windows-installer.py: Avoid writing nano.zip to disk

It's already in memory, and we're going to use it again immediately.
Avoiding the flush-to-disk is both more efficient, and easier to clean
up.

swc-windows-installer.py: Separate requests import from stdlib imports

Python-requests [1] is not part of the stdlib.

[1]: http://docs.python-requests.org/en/latest/

swc-windows-installer.py: Cleanup whitespace

swc-windows-installer.py: Setup msysgit to act like *nix systems

* Install `nano` 2.2.6.
* Add `ipython` and `nosetests` command line entry points.

get-my-ip.py: Python 2.x sockets can't be used in 'with' statements

They don't have __exit__.  Use an explicit try/except block to be
compatible with both 2.x and 3.x.

get-my-ip.py: Add a script for getting your public IP address

This will help students connect to each other on the LAN during class.
Note that if you ping a host across a NAT, you'll get your IP inside
the NAT, not the NAT's IP.

swc-installation-test-2.py: Use ProgramFiles environment variable

On Fri, Apr 26, 2013 at 11:45:12AM -0700, Onno Broekmans wrote:
> ... the installation paths you mention are incorrect for the
> majority of modern Windows 7 installations. These are 64-bit
> installations, and they have a special folder for 32-bit programs:
> "C:\Program Files (x86)". So Notepad++ can be found in:
>
>     C:\Program Files (x86)\Notepad++\notepad++.exe
>
> In the script, you could just check for the program's existence
> using both paths ("C:\Program Files" _and_ "C:\Program Files
> (x86)"), or you could use the "ProgramFiles" environment variable.

Environment variable it is!  From the Microsoft docs [1]:

  CSIDL_PROGRAM_FILESX86
    The Program Files folder on 64-bit systems. A typical path is
    C:\Program Files(86).
  ...
  CSIDL_PROGRAM_FILES
    Version 5.0. The Program Files folder. A typical path is
    C:\Program Files.
  ...
  PROGRAMFILES
    Same as CSIDL_PROGRAM_FILES.
  PROGRAMFILES(X86)
    Refers to the C:\Program Files (x86) folder on 64-bit systems.

We're just looking for executables, so it would be ok if we found a
32-bit Notepad++ or a 64-bit Notepad++.  With this commit, we check
both locations (if there are two distinct locations).

[1]: http://technet.microsoft.com/en-us/library/cc749104%28v=ws.10%29.aspx

swc-installation-test-2.py: Also look for extension-less paths

Before this commit, CommandDependency checked self.command (with an
optional extension determined by distutils).  If that check failed to
produce a version stream, we cycled through a list of additional
hard-coded paths.  For example:  Notepad++ used:

  self.command = 'notepad++'
  self.paths = [
      _os.path.join(
          _ROOT_PATH, 'Program Files', 'Notepad++', 'notepad++.exe'),
      ]

Because some MS Windows commands lack the expected '.exe' extension,
but are still present and detected by a number of shells, we should
also look for the extension-less version of the command.

I consolidated the _get_version_stream() logic to build a single list
of paths and loop through it looking for success (and accumulating
errors).  This makes the handling of self.paths less of a special
case, and sets us up for any additional path mangling we may need to
support other poorly standardized OSes ;).

swc-installation-test-2.py: Add CommandDependency.paths fallbacks

The old CommandDependency implementation assumed that commands would
exist in one of the directories listed in PATH.  This assumption is,
unfortunately, often not satisfied on MS Windows or OS X.  In order to
work around this problem, you can now store a list of fallback paths
that will be tried if there is an error extracting the version stream
from the bare CommandDependency.command.

I've added fallback paths for Notepad++, Firefox, and Google Chrome,
as reported by Ethan White for Windows 7.

swc-installation-test-2.py: Use _ROOT_PATH for MS Windows compatability

I don't think starting a path with os.sep gives you a root path on
Windows.  We need the backslash in _ROOT_PATH, because:

  os.path.join('c:', 'foo')

gives 'c:foo', a path relative to the current directory on drive C: [1].

[1]: http://docs.python.org/3/library/os.path.html#os.path.join

swc-installation-test-2.py: Raise an error on empty version stream

This makes the upcoming mult-path checking easier to implement.

swc-installation-test-2.py: Don't override Popen's 'close_fds'

Or 'shell'.  The support for these options can be flaky, and the
defaults change with Python version depending on what is best
supported [1].

[1]: http://docs.python.org/2/library/subprocess.html#subprocess.Popen

Reported-by: Ethan White <ethan@weecology.org>

swc-installation-test-2.py: Add 'safari'

This works adds support for virtual-browser on OS X.  Matt Davis
reports the locations of Firefox and Chrome as:

  /Applications/Firefox.app
  /Applications/Google\ Chrome.app

but I'm not sure where the executables live underneath those
directories, which we'd probably need if we wanted to extract version
numbers.

swc-installation-test-2.py: Link directly to install docs

Expecting the Software Carpentry maintainers to keep up-to-date
documentation for each system/package pair is not realistic.  Instead,
link to each package's installation instructions (as best I can find
them).  The system/version/package globbing (using fnmatch, see
glob(7)) makes it easy to setup per-system and per-version URLs if you
want to fine-tune the instructions.

swc-installation-test-2.py: Add --help and --verbose

The system information is useful for troubleshooting a student's
installation problems, but it is probably less useful for the student
themselves.  Turn off this troubleshooting information by default and
require the --verbose option to re-enable it.

If we didn't have to maintain support for Python 2.6, we could use
argparse instead of optparse.  The optparse module is deprecated for
2.7, 3.2, and later, but it is still part of the stdandard library.

Also update the README to point out --verbose.

swc-installation-test-2.py: List supported Ubuntu install hints

From http://software-carpentry.org/setup/ubuntu.html, in the order
that they are currently listed.  The page sections don't have the
appropriate anchor IDs yet, but it's still better to link to the
Ubuntu page than to the root setup/ page.

swc-installation-test-2.py: Add support for package-specific URLs

To give users more targeted advice for fixing their installation
problems, we should link them to somewhere more specific than the root
SWC setup page.  The two knobs in the specific URL are system/OS
(Gentoo, Debian, OS X, MS Windows, ...) and package (the dependency
name: emacs, git, virtual-browser, ...).  We don't have consistent
URLs upstream yet [1], but maybe this commit will help motivate them
;).

[1]: https://github.com/swcarpentry/website/issues/2

swc-installation-test-1.py: Link to s-c.o's terminal.html

For screen shots and additional platform support.

swc-installation-test-2.py: Add 'argparse'

I use this module (which entered the stdlib in 2.7/3.2) in my
get-my-ip.py script (in a different branch at the moment).  Users with
older Python implementations will have to install an external module
(e.g. from PyPI).

swc-installation-test-2.py: Add 'EasyMercurial'

Chris Cannam just released v1.3.0 which adds a --version option for
easy version testing [1].

[1]: https://bitbucket.org/cannam/easyhg/issue/1/teach-easymercurial-the-version-option

swc-installation-test-2.py: Initial EditorTaskDependency implementation

I'm not sold on this idea...

swc-installation-test-2.py: Add PathCommandDependency

OS X doesn't believe in $PATH ;).  Work around this heresy by simply
checking for the existence of a characteristic file or directory
(e.g. /Applications/SomeApp.app).  I use the new class to add 'xcode',
'sublime-text', 'textmate', and 'textwrangler' installations.

The location of the Xcode installation depends on your version of OS
X, and the 'xcode' comments show which path is expected for which
version.

swc-installation-test-2.py: Add TornadoPythonPackage for version extraction

Tornado follows Python's example with tornado.version and
tornado.version_info instead of using tornado.__version__.  While we
could parse tornado.version with our usual machinery, take advantage
of the pre-parsed version_info by defining a new class.

swc-installation-test-2.py: Add long names for virtual-* packages

Give a more user-friendly description of what we're checking for.

swc-installation-test-2.py: List all causes for or-dependency errors

Also make the and-dependency and or-dependency messages more friendly.

swc-installation-test-2.py: Add IPython notebook dependencies

You can get a successful IPython import even if you haven't installed
the dependencies you need for viewing notebooks.  This adds explicit
dependencies based on the current listings in IPython's setup.py.

swc-installation-test-2.py: Print full DependencyError chain

If a requirement is not satisfied due to an and_dependency or
or_dependency failure, raise a new DependencyError and attach the
original error as its cause (this would be easier if we didn't have to
preserve Python 2.x support).  This way we can print the whole chain
(e.g. virtual-shell failed because sh is not installed), instead of
just the lowest level error.

Also indent the messages, because:

  check for virtual-editor failed:
    or-dependency not satisfied for virtual-editor
    For instructions on installing an up-to-date version, see
    http://software-carpentry.org/setup/
    cause:
    check for Notepad++ (notepad++) failed:
      could not find 'notepad++' executable
      For instructions on installing an up-to-date version, see
      http://software-carpentry.org/setup/

is more readable than:

  check for virtual-editor failed:
  or-dependency not satisfied for virtual-editor
  For instructions on installing an up-to-date version, see
  http://software-carpentry.org/setup/
  cause:
  check for Notepad++ (notepad++) failed:
  could not find 'notepad++' executable
  For instructions on installing an up-to-date version, see
  http://software-carpentry.org/setup/

swc-installation-test-2.py: Add and_dependencies to Python package setup

Not used by any packages yet, but I'm about to use it for IPython.

swc-installation-test-2.py: Add gedit to virtual-editor

For Gnome users.

swc-installation-test-2.py: Add Pandas (pandas) >= 0.8

It's being used in 2013-01-columbia.

swc-installation-test-2.py: Handle unparsable versions gracefully

This avoids raising NotImplementedError from my IPython 0.14.dev.  We
don't want to have to start ranking alpha, beta, dev, r6, etc., so
just print the unparsable version and minimum version, and leave it to
the student to decide if their version satisfies the condition.  It's
unlikely that students have such pre-/post-release software installed
anyway.

swc-installation-test-2.py: Add ipython (script) >= 0.13

And make sure the IPython package has the same minimum version.
IPython 0.12 can't display more recent notebooks.

setup/README.md: Install-testing script care and feeding

setup: Move installation test scripts under setup/

There will be a lot of other stuff in the boot camp repository.  Stay
organized by keeping "how to set up and test your machine" stuff in a
subdirectory.

swc-installation-test-2.py: Comment out 'mercurial' dependency

There can be trouble detecting the Python package, especially on MS
Windows where the installed version of Python used to run the script
may not know about installed version of Mercurial.  Because nobody is
likely to use Mercurial's Python interface in a SWC class (they'll
probably stick to the command line interface), comment out this
dependency.

swc-installation-test-2.py: Add 'virtual-pypi-installer' and 'pip'

Students who need a Python Package Index (PyPI) installer should be
fine with either easy_install or pip [1].

[1]: http://pypi.python.org/pypi/pip
     http://www.pip-installer.org/

swc-installation-test: Return 1 on failure

I doubt anyone will check the exit status for these scripts, but it's
still good to follow conventions.

swc-installation-test-2.py: Better error message for unknown checks

swc-installation-test-2.py: Document command line arguments

swc-installation-test-2.py: Add MakeDependency class

On the fairly ancient SunOS 5.10 (January 2005), `make` doesn't
support `--version`.  Looking into the POSIX.2 specs [1], it doesn't
have to.  On FreeBSD [2] and in GNU Make [3], there is a MAKE_VERSION
variable, and the Sun executable has something similar:

  $ strings make | grep MAKE_VERSION
  .MAKE_VERSION

but it just expands to an empty string.

Since reading a makefile from stdin *is* in POSIX [1], we can use that
to test `make` if `make --version` fails.  If we get something for
MAKE_VERSION, use that.  If we get something for MAKE (required by
POSIX [2]), then call that a valid, but unkown, version.

[1]: http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html#tag_04_84_04
[2]: http://lists.freebsd.org/pipermail/freebsd-questions/2010-October/222214.html
[3]: http://www.gnu.org/software/make/manual/html_node/Features.html#index-MAKE_005fVERSION-1021
[4]: http://pubs.opengroup.org/onlinepubs/009695399/utilities/make.html#tag_04_84_13_08

swc-installation-test-2.py: Add CommandDependency.stdin

I'm about to implement a version check for 'make' where I want to pass
a test Makefile in via stdin.

swc-installation-test-2.py: Convert .version_option to .version_options

I'm about to implement a version check for 'make' where a single
option doesn't cut it.  For version of Python before 3.3,
shlex.quote() doesn't exist [1], so use pipes.quote() instead [2].

[1]: http://docs.python.org/3/library/shlex.html#shlex.quote
[2]: http://bugs.python.org/issue9723

swc-installation-test-2.py: Add OS-version detection

Using assorted functions from the `platform` module.  On my Linux box:

  $ python2.7
  Python 2.7.3 (default, Dec  5 2012, 10:56:01)
  [GCC 4.5.4] on linux2
  Type "help", "copyright", "credits" or "license" for more information.
  >>> import platform
  >>> platform.linux_distribution()
  ('Gentoo Base System', '2.1', '')
  >>> platform.mac_ver()
  ('', ('', '', ''), '')
  >>> platform.win32_ver()
  ('', '', '', '')

On an OS X box:

  $ python2.6
  Python 2.6.1 (r261:67515, Aug  2 2010, 20:10:18)
  [GCC 4.2.1 (Apple Inc. build 5646)] on darwin
  Type "help", "copyright", "credits" or "license" for more information.
  >>> import platform
  >>> platform.linux_distribution()
  ('', '', '')
  >>> platform.mac_ver()
  ('10.6.8', ('', '', ''), 'i386')
  >>> platform.win32_ver()
  ('', '', '', '')

I don't have access to an MS Windows box, but presumably it returns
something like:

  >>> platform.linux_distribution()
  ('', '', '')
  >>> platform.mac_ver()
  ('', ('', '', ''), '')
  >>> platform.win32_ver()
  ('XP', '5.1.2600', 'SP2', 'Multiprocessor Free')

We only want to print the one that applies (e.g. don't print a
'linux_distribution' entry on OS X), so we skip entries where value[0]
is an empty string.

swc-installation-test-2.py: Use the more portable platform.uname()

From the docs [1,2]:

  platform.uname():
    Fairly portable uname interface...  Entries which cannot be
    determined are set to ''.

  os.uname():
    ... Availability: recent flavors of Unix.

[1]: http://docs.python.org/2/library/platform.html#platform.uname
[2]: http://docs.python.org/2/library/os.html#os.uname

swc-installation-test-2.py: Isolate system-info indent in _print_info

This way shifting the indents if you add a longer key is a single-line
operation.

swc-installation-test-1.py: Give instructions for 'python command not found'

swc-installation-test-2.py: Sort shells in order of preference

Placing the often-symlinked `sh` at the end of the list.  This way if
a user has Bash installed, it doesn't show up as plain old Bourne.

swc-installation-test-2.py: Break after first successful or-dependency

No need to test the other dependencies once you find one that matches.

swc-installation-test-2.py: Give suggested install hints

I can't give package-specific links yet, but they will hopefully be in
place soon.  I made the "email your instructor" suggestion optional,
because it is easy for me to imagine a course large enough that the
instructor could not field all requests.  To disable, change

  print_suggestions(instructor_fallback=True)

to

  print_suggestions(instructor_fallback=False)

swc-installation-test-1.py: Give suggested install hints

This can link to the "howto setup Python" notes from SWC once those
get a more precise link than:

  http://software-carpentry.org/setup/