From c467e20e30a3704412ff697cac5b1bc6a064a6e5 Mon Sep 17 00:00:00 2001
From: Christoph Groth <christoph.groth@cea.fr>
Date: Tue, 22 Dec 2015 18:15:41 +0100
Subject: [PATCH] take into account Anton's suggestions
http://thread.gmane.org/gmane.comp.science.kwant.devel/40/focus=41
---
content/community.rst | 17 +++++++------
content/contribute.rst | 55 ++++++++++++++++++++----------------------
content/install.rst | 19 ++++++++-------
3 files changed, 45 insertions(+), 46 deletions(-)
diff --git a/content/community.rst b/content/community.rst
index 60cee37..87efe61 100644
--- a/content/community.rst
+++ b/content/community.rst
@@ -126,14 +126,15 @@ 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 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.
-
-A useful bug report should contain:
+you observe is actually a bug in Kwant. If you think it is, please check `the
+list of known bugs in Kwant
+<https://gitlab.kwant-project.org/kwant/kwant/issues?label_name=bug>`_. It
+may be also a good idea to search or ask on the general mailing list. (You can
+use the search box at the top of this page.)
+
+If after checking you still think that you have found a bug, please add it to
+the above-mentioned list of bugs by creating an issue with the “bug†label. A
+useful bug report should contain:
* The versions of software you are using (Kwant, Python, operating system, etc.)
diff --git a/content/contribute.rst b/content/contribute.rst
index d49fe5f..f45daed 100644
--- a/content/contribute.rst
+++ b/content/contribute.rst
@@ -97,33 +97,12 @@ 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.
+In the following, two methods to share your commits are described. The first
+will be familiar if you have experience with the popular GitHub service. If
+you do not, you might prefer the second method, since it is simpler.
-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
+Method 1: Using the Kwant GitLab instance
.........................................
Go the `GitLab page of the official Kwant repository
@@ -136,10 +115,10 @@ 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.
+You can copy-and-paste 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::
@@ -151,6 +130,24 @@ your branch by `creating a merge request in GitLab
sending a message to kwant-devel@kwant-project.org.
+Method 2: Sending patches to the development 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/>`_.)
+
+
Coding style
------------
diff --git a/content/install.rst b/content/install.rst
index 956b8bd..bb0ebf0 100644
--- a/content/install.rst
+++ b/content/install.rst
@@ -21,8 +21,9 @@ that are available for GNU/Linux (`Debian <#debian-and-derivatives>`_, `Ubuntu
and `Microsoft Windows`_.
Like most Python packages, `Kwant can be also installed using pip
-<#automatic-installation-using-pip>`_. (Note, however, that this will often
-result in a Kwant installation that runs significantly slower.)
+<#automatic-installation-using-pip>`_. (Be sure to follow this link, since
+naive use of pip will likely result in a Kwant installation with significantly
+reduced performance.)
If no packages are available for the system you use, or if you would like to
build Kwant from source for another reason (expert users may want to customize
@@ -34,16 +35,16 @@ Python 3 or Python 2
====================
Before installing Kwant, one has to decide which Python version to use –
-Python 3 or Python 2. `Python 3.0
+Python 3 or Python 2. (`Python 3.0
<https://docs.python.org/3/whatsnew/3.0.html>`_ was the first ever
intentionally backwards incompatible Python release, i.e. scripts that target
-Python 2 will typically not run with Python 3 and above unchanged.
+Python 2 will typically not run with Python 3 and above unchanged.)
-Kwant releases up to 1.1 require Python 2. Starting with release 1.2, we have
-`switched to Python 3 <http://kwant-project.org/doc/1/pre/whatsnew/1.2>`_. We
-recommend to use the latest Kwant with Python 3. Those who are stuck with
-Python 2 are invited to continue to use Kwant 1.1 which will be maintained for
-several years after 2015.
+Kwant releases up to 1.1 require Python 2. Starting with release 1.2, Kwant
+development has `switched to Python 3
+<http://kwant-project.org/doc/1/pre/whatsnew/1.2>`_. We recommend to use the
+latest Kwant with Python 3. Those who are stuck with Python 2 can continue to
+use Kwant 1.1 which will be maintained for several years after 2015.
The instructions below assume Python 3. They should be also valid for Python
2 if all occurrences of ``python3``, ``pip3``, etc. are replaced by
--
GitLab