DOC: updated gitwash docs and makefile for autoupdate

Author: satra

doc/Makefile

@@ -87,6 +87,12 @@ doctest:
 	@echo "Testing of doctests in the sources finished, look at the " \
 	      "results in _build/doctest/output.txt."
 
+gitwash-update:
+	python ../tools/gitwash_dumper.py devel nipype \
+            --project-url=http://nipy.org/nipype \
+            --project-ml-url=http://mail.scipy.org/mailman/listinfo/nipy-devel
+	@echo "gitwash updated"
+
 # Sourceforge doesn't appear to have a way of copying the files
 # without specifying a username.  So we'll probably have one target
 # for each project admin
@@ -101,7 +107,7 @@ sf_satra_nightly: html
 sf_satra: html
 	@echo "Copying html files to sourceforge..."
 	rsync -auv _build/html/. satra,nipy@web.sourceforge.net:htdocs/nipype/.
-	
+
 sf_filo: html
 	@echo "Copying html files to sourceforge..."
 	rsync -auv _build/html/. gorgolewski,nipy@web.sourceforge.net:htdocs/nipype/.

doc/devel/gitwash/configure_git.rst

@@ -113,11 +113,11 @@ Merging
 To enforce summaries when doing merges (``~/.gitconfig`` file again)::
 
    [merge]
-      summary = true
+      log = true
 
 Or from the command line::
 
-  git config --global merge.summary true
+  git config --global merge.log true
 
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/development_workflow.rst

@@ -4,16 +4,16 @@
 Development workflow
 ====================
 
-You already have your own forked copy of the Nipype_ repository, by
+You already have your own forked copy of the nipype_ repository, by
 following :ref:`forking`, :ref:`set-up-fork`, and you have configured
 git_ by following :ref:`configure-git`.
 
 Workflow summary
 ================
 
 * Keep your ``master`` branch clean of edits that have not been merged
-  to the main Nipype_ development repo.  Your ``master`` then will follow
-  the main Nipype_ repository.
+  to the main nipype_ development repo.  Your ``master`` then will follow
+  the main nipype_ repository.
 * Start a new *feature branch* for each set of edits that you do.
 * If you can avoid it, try not to merge other branches into your feature
   branch while you are working.
@@ -22,7 +22,7 @@ Workflow summary
 This way of working really helps to keep work well organized, and in
 keeping history as clear as possible.
 
-See - for example - `linux git workflow`_. 
+See |emdash| for example |emdash| `linux git workflow`_. 
 
 Making a new feature branch
 ===========================
@@ -33,7 +33,7 @@ Making a new feature branch
    git checkout my-new-feature
 
 Generally, you will want to keep this also on your public github_ fork
-of Nipype_.  To do this, you `git push`_ this new branch up to your github_
+of nipype_.  To do this, you `git push`_ this new branch up to your github_
 repo.  Generally (if you followed the instructions in these pages, and
 by default), git will have a link to your github_ repo, called
 ``origin``.  You push up to your own repo on github_ with::
@@ -87,29 +87,30 @@ In more detail
 #. To commit all modified files into the local copy of your repo,, do
    ``git commit -am 'A commit message'``.  Note the ``-am`` options to
    ``commit``. The ``m`` flag just signals that you're going to type a
-   message on the command line.  The ``a`` flag - you can just take on
-   faith - or see `why the -a flag?`_. See also the `git commit`_ manual
-   page.
+   message on the command line.  The ``a`` flag |emdash| you can just take on
+   faith |emdash| or see `why the -a flag?`_ |emdash| and the helpful use-case
+   description in the `tangled working copy problem`_. The `git commit`_ manual
+   page might also be useful.
 #. To push the changes up to your forked repo on github_, do a ``git
    push`` (see `git push`). 
 
 Asking for code review
 ======================
 
-#. Go to your repo URL - e.g. ``http://github.com/your-user-name/nipype``.
+#. Go to your repo URL |emdash| e.g. ``http://github.com/your-user-name/nipype``.
 #. Click on the *Branch list* button:
 
    .. image:: branch_list.png
 
-#. Click on the *Compare* button for your feature branch - here ``my-new-feature``:
+#. Click on the *Compare* button for your feature branch |emdash| here ``my-new-feature``:
 
    .. image:: branch_list_compare.png
 
 #. If asked, select the *base* and *comparison* branch names you want to
    compare.  Usually these will be ``master`` and ``my-new-feature``
    (where that is your feature branch name).
 #. At this point you should get a nice summary of the changes.  Copy the
-   URL for this, and post it to the `Nipype mailing list`_, asking for
+   URL for this, and post it to the `nipype mailing list`_, asking for
    review.  The URL will look something like:
    ``http://github.com/your-user-name/nipype/compare/master...my-new-feature``.
    There's an example at
@@ -135,14 +136,14 @@ When you are ready to ask for the merge of your code:
 
    .. image:: pull_button.png
 
-   Enter a message; we suggest you select only ``Nipype`` as the
-   recipient.  The message will go to the `Nipype mailing list`_.  Please
+   Enter a message; we suggest you select only ``nipype`` as the
+   recipient.  The message will go to the `nipype mailing list`_.  Please
    feel free to add others from the list as you like.
 
 Merging from trunk
 ==================
 
-This updates your code from the upstream `Nipype github`_  repo. 
+This updates your code from the upstream `nipype github`_  repo. 
 
 Overview
 --------
@@ -197,7 +198,7 @@ If you want to work on some stuff with other people, where you are all
 committing into the same repository, or even the same branch, then just
 share it via github_.
 
-First fork Nipype into your account, as from :ref:`forking`.
+First fork nipype into your account, as from :ref:`forking`.
 
 Then, go to your forked repository github page, say
 ``http://github.com/your-user-name/nipype``
@@ -235,4 +236,4 @@ To see a linear list of commits for this branch::
 You can also look at the `network graph visualizer`_ for your github_
 repo.
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/following_latest.rst

@@ -5,7 +5,7 @@
 =============================
 
 These are the instructions if you just want to follow the latest
-*Nipype* source, but you don't need to do any development for now.
+*nipype* source, but you don't need to do any development for now.
 
 The steps are:
 
@@ -18,7 +18,7 @@ Get the local copy of the code
 
 From the command line::
 
-   git clone git://github.com/nipy/nipype.git
+   git clone git://github.com/nipype/nipype.git
 
 You now have a copy of the code tree in the new ``nipype`` directory.
 
@@ -33,4 +33,4 @@ From time to time you may want to pull down the latest code.  Do this with::
 The tree in ``nipype`` will now have the latest changes from the initial
 repository.
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/forking_hell.rst

@@ -1,33 +1,33 @@
 .. _forking:
 
 ==========================================
-Making your own copy (fork) of Nipype
+Making your own copy (fork) of nipype
 ==========================================
 
 You need to do this only once.  The instructions here are very similar
-to the instructions at http://help.github.com/forking/ - please see that
-page for more detail.  We're repeating some of it here just to give the
-specifics for the Nipype_ project, and to suggest some default names.
+to the instructions at http://help.github.com/forking/ |emdash| please see
+that page for more detail.  We're repeating some of it here just to give the
+specifics for the nipype_ project, and to suggest some default names.
 
 Set up and configure a github_ account
 ======================================
 
 If you don't have a github_ account, go to the github_ page, and make one.
 
-You then need to configure your account to allow write access - see the
-``Generating SSH keys`` help on `github help`_.
+You then need to configure your account to allow write access |emdash| see
+the ``Generating SSH keys`` help on `github help`_.
 
-Create your own forked copy of Nipype_
-=========================================
+Create your own forked copy of nipype_
+===========================================
 
 #. Log into your github_ account.
-#. Go to the Nipype_ github home at `Nipype github`_.
+#. Go to the nipype_ github home at `nipype github`_.
 #. Click on the *fork* button:
 
    .. image:: forking_button.png
 
    Now, after a short pause and some 'Hardcore forking action', you
-   should find yourself at the home page for your own forked copy of Nipype_.
+   should find yourself at the home page for your own forked copy of nipype_.
 
-.. include:: git_links.inc
+.. include:: links.inc
 

doc/devel/gitwash/git_install.rst

@@ -23,4 +23,4 @@ Have a look at the github_ install help pages available from `github help`_
 
 There are good instructions here: http://book.git-scm.com/2_installing_git.html
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/git_intro.rst

@@ -2,11 +2,11 @@
  Introduction
 ==============
 
-These pages describe a git_ and github_ workflow for the Nipype_
+These pages describe a git_ and github_ workflow for the nipype_
 project.
 
 There are several different workflows here, for different ways of
-working with *Nipype*.
+working with *nipype*.
 
 This is not a comprehensive git_ reference, it's just a workflow for our
 own project.  It's tailored to the github_ hosting service. You may well
@@ -15,4 +15,4 @@ should get you started.
 
 For general resources for learning git_ see :ref:`git-resources`.
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/git_links.inc

@@ -8,31 +8,6 @@
    __not_case_sensitive__, so only one target definition is needed for
    nipy, NIPY, Nipy, etc...
 
-.. PROJECTNAME placeholders
-.. _PROJECTNAME: http://neuroimaging.scipy.org
-.. _`PROJECTNAME github`: http://github.com/nipy
-.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
-
-.. nipy
-.. _nipy: http://nipy.org/nipy
-.. _`nipy github`: http://github.com/nipy/nipy
-.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
-
-.. ipython
-.. _ipython: http://ipython.scipy.org
-.. _`ipython github`: http://github.com/ipython/ipython
-.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
-
-.. dipy
-.. _dipy: http://nipy.org/dipy
-.. _`dipy github`: http://github.com/Garyfallidis/dipy
-.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
-
-.. nipype
-.. _nipype: http://nipy.org/nipype
-.. _`nipype github`: http://github.com/nipy/nipype
-.. _`nipype mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
-
 .. git stuff
 .. _git: http://git-scm.com/
 .. _github: http://github.com
@@ -67,6 +42,13 @@
 .. _git config: http://www.kernel.org/pub/software/scm/git/docs/git-config.html
 .. _why the -a flag?: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
 .. _git staging area: http://www.gitready.com/beginner/2009/01/18/the-staging-area.html
+.. _tangled working copy problem: http://tomayko.com/writings/the-thing-about-git 
 .. _git management: http://kerneltrap.org/Linux/Git_Management
 .. _linux git workflow: http://www.mail-archive.com/dri-devel@lists.sourceforge.net/msg39091.html
 .. _git parable: http://tom.preston-werner.com/2009/05/19/the-git-parable.html
+.. _git foundation: http://matthew-brett.github.com/pydagogue/foundation.html
+
+.. other stuff
+.. _python: http://www.python.org
+
+.. |emdash| unicode:: U+02014

doc/devel/gitwash/git_resources.rst

@@ -14,12 +14,14 @@ Tutorials and summaries
 * The `git user manual`_ 
 * The `git tutorial`_
 * The `git community book`_
-* `git ready`_ - a nice series of tutorials
-* `git casts`_ - video snippets giving git how-tos.
-* `git magic`_ - extended introduction with intermediate detail
-* Fernando Perez' git page - `Fernando's git page`_ - many links and tips
+* `git ready`_ |emdash| a nice series of tutorials
+* `git casts`_ |emdash| video snippets giving git how-tos.
+* `git magic`_ |emdash| extended introduction with intermediate detail
+* The `git parable`_ is an easy read explaining the concepts behind git.
+* Our own `git foundation`_ expands on the `git parable`_.
+* Fernando Perez' git page |emdash| `Fernando's git page`_ |emdash| many
+  links and tips
 * A good but technical page on `git concepts`_
-* Th `git parable`_ is an easy read explaining the concepts behind git.
 * `git svn crash course`_: git_ for those of us used to subversion_
 
 Advanced git workflow
@@ -54,4 +56,4 @@ online manual pages for some common commands:
 * `git remote`_
 * `git status`_
 
-.. include:: git_links.inc
+.. include:: links.inc

doc/devel/gitwash/index.rst

@@ -1,6 +1,6 @@
 .. _using-git:
 
-Working with *Nipype* source code
+Working with *nipype* source code
 ======================================
 
 Contents:

doc/devel/gitwash/known_projects.inc

@@ -0,0 +1,41 @@
+.. Known projects
+
+.. PROJECTNAME placeholders
+.. _PROJECTNAME: http://neuroimaging.scipy.org
+.. _`PROJECTNAME github`: http://github.com/nipy
+.. _`PROJECTNAME mailing list`: http://projects.scipy.org/mailman/listinfo/nipy-devel
+
+.. numpy
+.. _numpy: hhttp://numpy.scipy.org
+.. _`numpy github`: http://github.com/numpy/numpy
+.. _`numpy mailing list`: http://mail.scipy.org/mailman/listinfo/numpy-discussion
+
+.. scipy
+.. _scipy: http://www.scipy.org
+.. _`scipy github`: http://github.com/scipy/scipy
+.. _`scipy mailing list`: http://mail.scipy.org/mailman/listinfo/scipy-dev
+
+.. nipy
+.. _nipy: http://nipy.org/nipy
+.. _`nipy github`: http://github.com/nipy/nipy
+.. _`nipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. ipython
+.. _ipython: http://ipython.scipy.org
+.. _`ipython github`: http://github.com/ipython/ipython
+.. _`ipython mailing list`: http://mail.scipy.org/mailman/listinfo/IPython-dev
+
+.. dipy
+.. _dipy: http://nipy.org/dipy
+.. _`dipy github`: http://github.com/Garyfallidis/dipy
+.. _`dipy mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. nibabel
+.. _nibabel: http://nipy.org/nibabel
+.. _`nibabel github`: http://github.com/nipy/nibabel
+.. _`nibabel mailing list`: http://mail.scipy.org/mailman/listinfo/nipy-devel
+
+.. marsbar
+.. _marsbar: http://marsbar.sourceforge.net
+.. _`marsbar github`: http://github.com/matthew-brett/marsbar
+.. _`MarsBaR mailing list`: https://lists.sourceforge.net/lists/listinfo/marsbar-users

doc/devel/gitwash/links.inc

@@ -0,0 +1,4 @@
+.. compiling links file
+.. include:: known_projects.inc
+.. include:: this_project.inc
+.. include:: git_links.inc