expand "how to contribute", make it an own page

conf.py

@@ -129,6 +129,8 @@ NAVIGATION_LINKS = {
         "<span class='hidden-xs'>documentation</span>"),
         ("/community.html", "<i class='glyphicon glyphicon-comment visible-xs-inline-block'></i>"
         "<span class='hidden-xs'>community</span>"),
+        ("/contribute.html", "<i class='glyphicon glyphicon-wrench visible-xs-inline-block'></i>"
+        "<span class='hidden-xs'>contribute</span>"),
         ("/authors.html", "<i class='glyphicon glyphicon-user visible-xs-inline-block'></i>"
         "<span class='hidden-xs'>authors</span>"),
         ("/cite.html", "<i class='glyphicon glyphicon-edit visible-xs-inline-block'></i>"

content/community.rst

-Getting help, contributing and reporting problems
-=================================================
+Getting in touch with the Kwant community
+=========================================
 
 General mailing list
 --------------------
@@ -114,14 +114,16 @@ Kwant.  Only a few messages will be sent per year.  These announcements will be
 Reporting bugs
 --------------
 
-If you encounter a problem with Kwant, first try to reproduce it with as simple
-a system as possible.  Double-check with the documentation that what you observe
-is actually a bug in Kwant. If you think it is, please check whether the problem
-is already known by searching the general mailing list. (You may use the search
-box at the top of this page.)
+If you encounter a problem with Kwant, first try to reproduce it with as
+simple a system as possible.  Double-check with the documentation that what
+you observe is actually a bug in Kwant. If you think it is, please check
+whether the problem is already known in the `Kwant bugtracker
+<https://gitlab.kwant-project.org/kwant/kwant/issues?label_name=bug>`_.  It can
+be also a good idea to search the general mailing list. (You may use the
+search box at the top of this page.)  If you are unsure whether something is a
+bug or not, please do ask on the mailing list.
 
-If the problem is not known yet, please send a bug report to
-kwant-discuss@kwant-project.org.  A report should contain:
+A useful bug report should contain:
 
 * The versions of software you are using (Kwant, Python, operating system, etc.)
 
@@ -129,98 +131,3 @@ kwant-discuss@kwant-project.org.  A report should contain:
 
 * Enough information to reproduce the bug, preferably in the form of a simple
   script.
-
-
-Contributing
-------------
-
-We see Kwant not just as a package with fixed functionality, but rather as a
-framework for implementing different physics-related algorithms using a common
-set of concepts and, if possible, a shared interface.  We have designed it
-leaving room for growth, and plan to keep extending it.
-
-External contributions to Kwant are highly welcome.  You can help to advance
-the project not only by writing code, but also by reporting bugs, and
-fixing/improving the documentation.
-
-If you have some code that works well with Kwant, or extends it in some useful
-way, please consider sharing it.  Any external contribution will be clearly
-marked as such, and relevant papers will be added to the list of `suggested
-acknowledgements </citing.html>`_.  The complete development history is also
-made available through a `web interface <http://gitlab.kwant-project.org/kwant/kwant/commits/master>`_.
-If you plan to contribute, it is best to coordinate with us in advance either
-through the development mailing list kwant-devel@kwant-project.org, or directly at
-authors@kwant-project.org for matters that you prefer to not discuss publicly.
-
-
-How to contribute
-.................
-
-We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
-development of Kwant.  If you are new to Git, we invite you to learn its basics.
-(There's a plethora of information available on the Web.)  Kwant's Git
-repository contains not only the source code, but also all of the reference
-documentation and the tutorial.
-
-It is best to base your work on the latest version of Kwant::
-
-    git clone https://gitlab.kwant-project.org/kwant/kwant.git
-
-Then you can build Kwant and the documentation as
-described in the `build instructions
-</doc/1/pre/install.html#building-and-installing-from-source>`_.
-
-The Kwant git repository has two main branches: The branch *master*
-contains the development towards the next release.  The branch *stable* contains
-the most recent release that is considered stable, and only bugfixes are applied
-to it.
-
-We recommend that you keep your changes on a separate `topic branch
-<https://www.kernel.org/pub/software/scm/git/docs/gitworkflows.html#_topic_branches>`_
-that starts at *master*.  To create such a branch, use the command::
-
-    git checkout -b my_topic_branch master
-
-Once you have something that you would like to share, let us know about it by
-posting to kwant-devel@kwant-project.org.  We are happy to receive useful
-contributions in any reasonable way: you can send patches to the mailing list,
-make your git repository available on the web (you could use a service like
-github), or even directly send the file that you modified.
-
-The recommended way is sending patches to the mailing list.  (This avoids
-confusion by publishing unfinished git branches and allows code review.)  See
-this `example of usage
-<https://kernel.org/pub/software/scm/git/docs/git-send-email.html#_example>`_
-and this `git send-email howto
-<http://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/>`_,
-it’s easy.
-
-Some things to keep in mind:
-
-* Please keep the code consistent by adhering to the prevailing naming and
-  formatting conventions.  We generally follow the `"Style Guide for Python
-  Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
-  `NumPy's "Docstring Standard"
-  <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
-  `Python's "Docstring Conventions"
-  <http://www.python.org/dev/peps/pep-0257/>`_.
-
-* Write tests for all the important functionality you add.  Be sure not to
-  break existing tests.
-
-* Create a logical sequence of commits with clear commit messages.
-
-A useful trick for working on the source code is to build in-place so that there
-is no need to re-install after each change.  This can be done with the following
-command ::
-
-    python setup.py build_ext -i --cython
-
-The ``kwant`` subdirectory of the source distribution will be thus turned into
-a proper Python package that can be imported.  To be able to import Kwant from
-within Python, one can either work in the root directory of the distribution
-(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
-somewhere in the Python search path to the the package subdirectory.
-
-The option ``--cython`` enables the translation of .pyx files into .c files.
-It is only needed if any .pyx files have been modified.

content/contribute.rst

+Contributing to Kwant
+=====================
+
+We see Kwant not just as a package with fixed functionality, but rather as a
+framework for implementing different physics-related algorithms using a common
+set of concepts and, if possible, a shared interface.  We have designed it
+leaving room for growth, and plan to keep extending it.
+
+Contributions to Kwant are highly welcome.  You can help the project not only
+by writing code, but also by reporting bugs, and fixing/improving the
+website and the documentation.
+
+
+Where help is needed
+--------------------
+
+The `Kwant issue tracker
+<https://gitlab.kwant-project.org/kwant/kwant/issues>`_ serves to track bugs
+in Kwant, but most issues are in fact ideas for enhancements.  The issues are
+categorized with labels, so that it is possible to view `all the “easy” issues
+<https://gitlab.kwant-project.org/kwant/kwant/issues?label_name=difficulty%3A+easy>`_
+for example.
+
+Please do feel free to enter new issues yourself.  If you are unsure about
+some aspect It may be a good idea to discuss your idea on the development
+mailing list kwant-devel@kwant-project.org before filing an issue.
+
+If you already have some code that extends Kwant in a useful way, please
+consider sharing it.  If your extension fits well with Kwant and is of wide
+enough interest, we will be happy to include it into Kwant proper.  For more
+specialized cases, we will find a solution as well.  (We could, for example,
+add a list of Kwant-related modules to this website.)  In any case, external
+contributions will be clearly marked as such, and relevant papers will be
+added to the list of `suggested acknowledgements </cite.html>`_.
+
+
+Getting the source code
+-----------------------
+
+The source code of released versions of Kwant is available for `download
+<http://downloads.kwant-project.org/kwant/>`_.  You can follow the development
+through the `Kwant page of our GitLab instance
+<https://gitlab.kwant-project.org/kwant/kwant>`_.  The `Git
+<http://git-scm.com/>`_ repository of Kwant can be cloned directly with the
+command ::
+
+    git clone https://gitlab.kwant-project.org/kwant/kwant.git
+
+The Kwant git repository has two main branches: The branch *master*
+contains the development towards the next release.  The branch *stable* contains
+the most recent release that is considered stable, and only bugfixes are applied
+to it.
+
+
+Setting up for development
+--------------------------
+
+When working with the Kwant source, regular `build instructions
+</doc/1/pre/install.html#building-and-installing-from-source>`_ apply.  It
+would be tiresome, however, to have to reinstall the modified Kwant after each
+modification.
+
+One easy way to avoid this is to build in-place so that there is no need to
+reinstall after each change.  This can be done with the following command ::
+
+    python3 setup.py build_ext -i
+
+No further installation is necessary.  The “inner” ``kwant`` subdirectory has
+been turned into a proper Python package that can be imported from the “outer”
+directory, i.e. the directory where ``setup.py`` is located.  Any script
+inside that directory that imports Kwant will get the modified version.  (To
+be able to import the modified Kwant from another directory one can create a
+symbolic link to the package.)
+
+The above ``build_ext`` command does not have to be rerun when a Python file
+is modified.  Recompilation is only necessary whenever a Cython file
+(``.pyx``) has been changed.
+
+
+Modifying the source code
+-------------------------
+
+We recommend that you keep each of your changes to Kwant on a separate “topic
+branch” that starts at *master*.  Try to not mix up unrelated changes in a
+single branch.  To create a topic branch, use the command::
+
+    git checkout -b my_topic master
+
+Now you can begin to implement your idea.  As you go, register your changes
+with Git as explained, for example, in the `Pro Git book
+<https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository>`_
+that is freely available online.
+
+Once you feel that you would like to show your work to other interested people
+(because you would like to receive feedback, or because you consider it
+ready), it's time to inspect your branch.  Run ``git status`` to make sure
+that you have committed all of your changes, then use a tool like ``gitk`` to
+view your branch.
+
+In the following two methods to share your commits are described.  The first
+one requires only minimal setup, the second will be familiar to people who use
+the popular GitHub service.
+
+
+Method 1: Sending patches to the development mailing list
+.........................................................
+
+The simplest way to let the community know about your change is to send
+patches to the mailing list.
+
+Run the command ::
+
+    git format-patch origin/master
+
+This will create “patch” file for each commit on your branch.  Now simply send
+these patches as email attachments to kwant-devel@kwant-project.org, together
+with an explanation of your idea.  You do not have to be subscribed to the
+mailing list.
+
+(Or, even better, use ``git send-email`` as shown in this `example of usage
+<https://kernel.org/pub/software/scm/git/docs/git-send-email.html#_example>`_
+and this `git send-email howto
+<http://www.freedesktop.org/wiki/Software/PulseAudio/HowToUseGitSendEmail/>`_.)
+
+
+Method 2: Using the Kwant GitLab instance
+.........................................
+
+Go the `GitLab page of the official Kwant repository
+<https://gitlab.kwant-project.org/kwant/kwant>`_.  Since you do not have write
+access to this repository, you have to create an own “fork” of it by clicking
+on the button just right of the “star” button.
+
+You created a public copy of the Kwant repository that is controlled by you.
+Add it as a remote repository to the clone of Kwant on your computer::
+
+    git remote add own https://gitlab.kwant-project.org/<USERNAME>/kwant.git
+
+You can copy your own version of the above URL from the main page of your
+repository.  (If you know about SSH, you may also prefer to upload your public
+ssh key to GitLab and to use SSH as transport.)  The string ``own`` is the
+local name you give to the remote, it can be anything.
+
+Now you can push your topic branch to your repository::
+
+    git push own my_branch
+
+This will make your branch appear in GitLab.  Now you can let us know about
+your branch by `creating a merge request in GitLab
+<https://gitlab.kwant-project.org/help/workflow/forking_workflow.md>`_ or by
+sending a message to kwant-devel@kwant-project.org.
+
+
+Coding style
+------------
+
+* Please keep the code consistent by adhering to the prevailing naming and
+  formatting conventions.  We generally respect the `"Style Guide for Python
+  Code" <http://www.python.org/dev/peps/pep-0008/>`_.  For docstrings, we
+  follow `NumPy's "Docstring Standard"
+  <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
+  `Python's "Docstring Conventions"
+  <http://www.python.org/dev/peps/pep-0257/>`_.
+
+* Write tests for all the important functionality you add.  Be sure not to
+  break existing tests.
+
+* Create a logical sequence of commits with clear commit messages.

htaccess-apache

@@ -33,5 +33,4 @@ RewriteRule ^(.*)/$  /$1 [R=301,L]
 Redirect 302 /2015-survey https://docs.google.com/forms/d/1j0LiFdZLjvfwoEyg5FML6z3sFKqV3Ar1mWReonYhatA/viewform
 Redirect 302 /contact /authors
 Redirect 302 /citing /cite
-Redirect 302 /contribute /community
 Redirect 302 /download /install