GitList
Browse code

update CONTRIBUTE.rst

Christoph Groth authored on 08/01/2018 22:05:53
Showing 1 changed files
CONTRIBUTE.rst
History View file @ 56847aa
... ... 
@@ -4,11 +4,8 @@ Contributing to Kwant and reporting problems
4 4
5 5 
 We see Kwant not just as a package with fixed functionality, but rather as a
6 6 
 framework for implementing different physics-related algorithms using a common
7 
-set of concepts and, if possible, a shared interface.  We have designed it
8 
-leaving room for growth, and plan to keep extending it.
9 
-
10 
-External contributions to Kwant are highly welcome.  You can help to advance
11 
-the project not only by writing code, but also by reporting bugs, and
12 
-fixing/improving the documentation.  Please see the `Kwant website
13 
-<https://kwant-project.org/community>`_ for information on how to get in touch
14 
-with the Kwant community.
7 
+set of concepts. Contributions to Kwant are highly welcome. You can help the
8 
+project not only by writing code, but also by reporting bugs, and
9 
+fixing/improving the website and the documentation. Please see the
10 
+`"Contributing" page <https://kwant-project.org/contribute>`_ of the Kwant
11 
+website for more information.
Browse code

prepare a more detailed test suit, fix minor typos

Summary of changes:
* Add a test for trailing whitespace, remove all trailling whitespace
* Add a test for broken URLs in docs, fix all broken URLs and permanent redirects
* Switch sphinx doc build to strict (warnings to errors) and nitpicky (broken links to warnings). Fix all sphinx warnings.
* Deploy docs from any commit to [kwant/kwant](https://gitlab.kwant-project.org/kwant/kwant) to https://test.kwant-project.org/doc/dev
* Deploy docs from any commit to master at kwant/kwant to https://kwant-project.org/doc/dev
* Deploy docs from any tag release tag (so anything that is vX.Y.Z) at kwant/kwant to https://kwant-project.org/doc/X.Y

Anton Akhmerov authored on 05/08/2016 22:57:01
Showing 1 changed files
CONTRIBUTE.rst
History View file @ 164f611
... ... 
@@ -10,5 +10,5 @@ leaving room for growth, and plan to keep extending it.
10 10 
 External contributions to Kwant are highly welcome.  You can help to advance
11 11 
 the project not only by writing code, but also by reporting bugs, and
12 12 
 fixing/improving the documentation.  Please see the `Kwant website
13 
-<http://kwant-project.org/community>`_ for information on how to get in touch
13 
+<https://kwant-project.org/community>`_ for information on how to get in touch
14 14 
 with the Kwant community.
Browse code

revise installation and contribution instructions

I try to cleanly separate between information that should be part of the
Kwant source distribution (that is tied to a particular version of
Kwant), and generic information that is best presented on the website.

Christoph Groth authored on 03/12/2015 18:53:19
Showing 1 changed files
CONTRIBUTE.rst
History View file @ a526e8f
... ... 
@@ -9,76 +9,6 @@ leaving room for growth, and plan to keep extending it.
9 9
10 10 
 External contributions to Kwant are highly welcome.  You can help to advance
11 11 
 the project not only by writing code, but also by reporting bugs, and
12 
-fixing/improving the documentation.  A `mailing list
13 
-<http://kwant-project.org/community.html>`_ is available for discussions.
14 
-
15 
-If you have some code that works well with Kwant, or extends it in some useful
16 
-way, please consider sharing it.  Any external contribution will be clearly
17 
-marked as such, and relevant papers will be added to the list of
18 
-:doc:`suggested acknowledgements <citing>`.  The complete development history
19 
-is also made available through a `web interface
20 
-<http://git.kwant-project.org/kwant>`_.  If you plan to contribute, it is best
21 
-to coordinate with us in advance either through the `mailing list
22 
-<http://kwant-project.org/community.html>`__, or directly by `email
23 
-<mailto:authors@kwant-project.org>`_ for matters that you prefer to not discuss
24 
-publicly.
25 
-
26 
-Reporting bugs
27 
-
28 
-If you encounter a problem with Kwant, first try to reproduce it with as simple
29 
-a system as possible.  Double-check with the documentation that what you
30 
-observe is actually a bug in Kwant. If you think it is, please check whether
31 
-the problem is already known by searching the `mailing list
32 
-<http://kwant-project.org/community.html>`__.
33 
-
34 
-If the problem is not known yet, please email a bug report to the `Kwant mailing
35 
-list <http://kwant-project.org/community.html>`__. A report should contain:
36 
-
37 
-* The versions of software you are using (Kwant, Python, operating system, etc.)
38 
-
39 
-* A description of the problem, i.e. what exactly goes wrong.
40 
-
41 
-* Enough information to reproduce the bug, preferably in the form of a simple
42 
-  script.
43 
-
44 
-How to contribute
45 
-
46 
-We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
47 
-development of Kwant.  If you are new to Git, we invite you to learn its basics.
48 
-(There's a plethora of information available on the Web.)  Kwant's Git
49 
-repository contains not only the source code, but also all of the reference
50 
-documentation and the tutorial.
51 
-
52 
-It is best to base your work on the latest version of Kwant::
53 
-
54 
-    git clone http://git.kwant-project.org/kwant
55 
-
56 
-Then you can modify the code, and build Kwant and the documentation as described
57 
-in the :doc:`installation instructions <install>`.
58 
-
59 
-Some things to keep in mind:
60 
-
61 
-* Please keep the code consistent by adhering to the prevailing naming and
62 
-  formatting conventions.  We generally follow the `"Style Guide for Python
63 
-  Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
64 
-  `NumPy's "Docstring Standard"
65 
-  <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
66 
-  `Python's "Docstring Conventions"
67 
-  <http://www.python.org/dev/peps/pep-0257/>`_.
68 
-
69 
-* Write tests for all the important functionality you add.  Be sure not to
70 
-  break existing tests.
71 
-
72 
-A useful trick for working on the source code is to build in-place so that there
73 
-is no need to re-install after each change.  This can be done with the following
74 
-command ::
75 
-
76 
-    python setup.py build_ext -i
77 
-
78 
-The ``kwant`` subdirectory of the source distribution will be thus turned into
79 
-a proper Python package that can be imported.  To be able to import Kwant from
80 
-within Python, one can either work in the root directory of the distribution
81 
-(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
82 
-somewhere in the Python search path to the the package subdirectory.
12 
+fixing/improving the documentation.  Please see the `Kwant website
13 
+<http://kwant-project.org/community>`_ for information on how to get in touch
14 
+with the Kwant community.
Browse code

setup.py: implicitly enable --cython when running from git

Christoph Groth authored on 25/10/2015 15:46:47
Showing 1 changed files
CONTRIBUTE.rst
History View file @ c0a7ad6
... ... 
@@ -75,13 +75,10 @@ A useful trick for working on the source code is to build in-place so that there
75 75 
 is no need to re-install after each change.  This can be done with the following
76 76 
 command ::
77 77
78 
-    python setup.py build_ext -i --cython
78 
+    python setup.py build_ext -i
79 79
80 80 
 The ``kwant`` subdirectory of the source distribution will be thus turned into
81 81 
 a proper Python package that can be imported.  To be able to import Kwant from
82 82 
 within Python, one can either work in the root directory of the distribution
83 83 
 (where the subdirectory ``kwant`` is located), or make a (symbolic) link from
84 84 
 somewhere in the Python search path to the the package subdirectory.
85 
-
86 
-The option ``--cython`` enables the translation of .pyx files into .c files.
87 
-It is only needed if any .pyx files have been modified.
Browse code

setup.py: disable cython by default

The pip tool messes up the timestamps of files, so with our previous strategy
of enabling cython by default the build fails if Cython is not available.

Also, turn the "warning" into a "caution" message that is less frightening and
send it to stdout only, so that it does not appear with pip.

Christoph Groth authored on 21/10/2015 18:05:01
Showing 1 changed files
CONTRIBUTE.rst
History View file @ b904e2b
... ... 
@@ -75,10 +75,13 @@ A useful trick for working on the source code is to build in-place so that there
75 75 
 is no need to re-install after each change.  This can be done with the following
76 76 
 command ::
77 77
78 
-    python setup.py build_ext -i
78 
+    python setup.py build_ext -i --cython
79 79
80 80 
 The ``kwant`` subdirectory of the source distribution will be thus turned into
81 81 
 a proper Python package that can be imported.  To be able to import Kwant from
82 82 
 within Python, one can either work in the root directory of the distribution
83 83 
 (where the subdirectory ``kwant`` is located), or make a (symbolic) link from
84 84 
 somewhere in the Python search path to the the package subdirectory.
85 
+
86 
+The option ``--cython`` enables the translation of .pyx files into .c files.
87 
+It is only needed if any .pyx files have been modified.
Browse code

add rst-extension to README (and similar files), expand README.rst into a PyPI-"homepage"

Christoph Groth authored on 03/02/2015 17:47:59
Showing 1 changed files
CONTRIBUTE.rst
History View file @ c6e82aa
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,84 @@
1 
+============================================
2 
+Contributing to Kwant and reporting problems
3 
+============================================
4 
+
5 
+We see Kwant not just as a package with fixed functionality, but rather as a
6 
+framework for implementing different physics-related algorithms using a common
7 
+set of concepts and, if possible, a shared interface.  We have designed it
8 
+leaving room for growth, and plan to keep extending it.
9 
+
10 
+External contributions to Kwant are highly welcome.  You can help to advance
11 
+the project not only by writing code, but also by reporting bugs, and
12 
+fixing/improving the documentation.  A `mailing list
13 
+<http://kwant-project.org/community.html>`_ is available for discussions.
14 
+
15 
+If you have some code that works well with Kwant, or extends it in some useful
16 
+way, please consider sharing it.  Any external contribution will be clearly
17 
+marked as such, and relevant papers will be added to the list of
18 
+:doc:`suggested acknowledgements <citing>`.  The complete development history
19 
+is also made available through a `web interface
20 
+<http://git.kwant-project.org/kwant>`_.  If you plan to contribute, it is best
21 
+to coordinate with us in advance either through the `mailing list
22 
+<http://kwant-project.org/community.html>`__, or directly by `email
23 
+<mailto:authors@kwant-project.org>`_ for matters that you prefer to not discuss
24 
+publicly.
25 
+
26 
+Reporting bugs
27 
+--------------
28 
+
29 
+If you encounter a problem with Kwant, first try to reproduce it with as simple
30 
+a system as possible.  Double-check with the documentation that what you
31 
+observe is actually a bug in Kwant. If you think it is, please check whether
32 
+the problem is already known by searching the `mailing list
33 
+<http://kwant-project.org/community.html>`__.
34 
+
35 
+If the problem is not known yet, please email a bug report to the `Kwant mailing
36 
+list <http://kwant-project.org/community.html>`__. A report should contain:
37 
+
38 
+* The versions of software you are using (Kwant, Python, operating system, etc.)
39 
+
40 
+* A description of the problem, i.e. what exactly goes wrong.
41 
+
42 
+* Enough information to reproduce the bug, preferably in the form of a simple
43 
+  script.
44 
+
45 
+How to contribute
46 
+-----------------
47 
+
48 
+We use the version control system `Git <http://git-scm.com/>`_ to coordinate the
49 
+development of Kwant.  If you are new to Git, we invite you to learn its basics.
50 
+(There's a plethora of information available on the Web.)  Kwant's Git
51 
+repository contains not only the source code, but also all of the reference
52 
+documentation and the tutorial.
53 
+
54 
+It is best to base your work on the latest version of Kwant::
55 
+
56 
+    git clone http://git.kwant-project.org/kwant
57 
+
58 
+Then you can modify the code, and build Kwant and the documentation as described
59 
+in the :doc:`installation instructions <install>`.
60 
+
61 
+Some things to keep in mind:
62 
+
63 
+* Please keep the code consistent by adhering to the prevailing naming and
64 
+  formatting conventions.  We generally follow the `"Style Guide for Python
65 
+  Code" <http://www.python.org/dev/peps/pep-0008/>`_ For docstrings, we follow
66 
+  `NumPy's "Docstring Standard"
67 
+  <http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_ and
68 
+  `Python's "Docstring Conventions"
69 
+  <http://www.python.org/dev/peps/pep-0257/>`_.
70 
+
71 
+* Write tests for all the important functionality you add.  Be sure not to
72 
+  break existing tests.
73 
+
74 
+A useful trick for working on the source code is to build in-place so that there
75 
+is no need to re-install after each change.  This can be done with the following
76 
+command ::
77 
+
78 
+    python setup.py build_ext -i
79 
+
80 
+The ``kwant`` subdirectory of the source distribution will be thus turned into
81 
+a proper Python package that can be imported.  To be able to import Kwant from
82 
+within Python, one can either work in the root directory of the distribution
83 
+(where the subdirectory ``kwant`` is located), or make a (symbolic) link from
84 
+somewhere in the Python search path to the the package subdirectory.