.coveragerc

+[run]
+plugins = Cython.Coverage
+omit =
+     */tests/*
+     kwant/graph/dissection.py
+     kwant/_kwant_version.py
+     */__init__.py
+branch = True
+[report]
+exclude_lines =
+    skip coverage
+    @abc.abstractmethod
+    @abc.abstractproperty

.gitattributes

+kwant/_kwant_version.py export-subst

.gitignore

@@ -2,17 +2,19 @@
 *.pyc
 *.pyo
 *.so
+*.pyd
 /kwant/*.c
 /kwant/*/*.c
-/tutorial
 /build
 /dist
 /doc/build
 /doc/source/reference/generated/
-/doc/source/images/*.png
-/doc/source/images/*.pdf
-/doc/source/images/.*_flag
-/doc/source/images/[a-zA-Z]*.py
+/doc/source/figure/*.pdf
 /build.conf
 /kwant.egg-info/
 /MANIFEST.in
+.cache/
+.coverage
+.eggs/
+htmlcov/
+.ipynb_checkpoints/

.gitlab-ci.yml

-job:
+image: gitlab.kwant-project.org:5005/kwant/kwant
+
+stages:
+  - build-env
+  - build
+  - test
+  - deploy
+  - release
+
+before_script:
+  # Here and below, a workaround for gitlab runner not fetching tags
+  # See https://gitlab.com/gitlab-org/gitaly/-/issues/2221
+  - git config --global --add safe.directory /builds/kwant/kwant
+  - git fetch --tags
+
+variables:
+  # rsync is used to send documentation to our web servers: we never send any
+  # secret information, and using 'ssh-keyscan' causes the CI server's IP to be blacklisted
+  SSH_COMMAND: "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null"
+  # Turn off threading to avoid slowdowns
+  OPENBLAS_NUM_THREADS : 1
+  OMP_NUM_THREADS : 1
+  MKL_DYNAMIC : FALSE
+  MKL_NUM_THREADS : 1
+
+## Building Docker environments
+## Only runs when docker specifications change
+
+.build-env:
+  stage: build-env
+  when: manual
+  image:
+    name: gcr.io/kaniko-project/executor:debug
+    entrypoint: [""]
+  before_script:
+    - mkdir -p /kaniko/.docker
+    - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+build-env:ubuntu:
+  extends: .build-env
   script:
-    - python3 setup.py build
-    - python3 setup.py build_ext -i
-    - make -C doc clean && make -C doc html
-    - nosetests3 --with-coverage --cover-package kwant
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.ubuntu
+      --destination $CI_REGISTRY_IMAGE/ubuntu
+
+build-env:debian:
+  extends: .build-env
+  script:
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.debian
+      --destination $CI_REGISTRY_IMAGE/debian
+
+build-env:default:
+  extends: .build-env
+  script:
+    - /kaniko/executor
+      --context $CI_PROJECT_DIR/docker
+      --dockerfile $CI_PROJECT_DIR/docker/Dockerfile.conda
+      --destination $CI_REGISTRY_IMAGE
+
+
+## Build environment specifications
+
+.build:
+  stage: build
+  script:
+    - echo -e "[DEFAULT]\ndefine_macros = CYTHON_TRACE=1 NPY_NO_DEPRECATED_API=NPY_1_7_API_VERSION" >build.conf
+    - ./setup.py build
+    - ./setup.py build_ext -i
+  artifacts:
+    untracked: true
+    expire_in: 2 hour
+
+
+.stable-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-stable
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.no-extras-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-stable-no-extras
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+# Note that this is 'latest' as of when the image was last built
+.latest-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-latest
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.bleeding-edge-env:
+  before_script:
+    - eval "$(micromamba shell hook --shell bash)"
+    - micromamba activate kwant-latest
+    - micromamba update --all
+    - git config --global --add safe.directory /builds/kwant/kwant
+    - git fetch --tags
+
+.ubuntu-env:
+  image: gitlab.kwant-project.org:5005/kwant/kwant/ubuntu
+
+.debian-env:
+  image: gitlab.kwant-project.org:5005/kwant/kwant/debian
+
+## Build Jobs
+
+build:ubuntu:
+  extends:
+    - .build
+    - .ubuntu-env
+
+build:debian:
+  extends:
+    - .build
+    - .debian-env
+
+build:stable:
+  extends:
+    - .build
+    - .stable-env
+
+build:no-extras:
+  extends:
+    - .build
+    - .no-extras-env
+
+build:latest:
+  extends:
+    - .build
+    - .latest-env
+
+build:bleeding-edge:
+  extends:
+    - .build
+    - .bleeding-edge-env
+  only:
+    - schedules
+  allow_failure: true
+
+## Test Jobs
+
+check whitespace style:
+  stage: test
+  script: ./check_whitespace
+  allow_failure: true
+
+check for dependencies installed:
+  stage: test
+  script:
+    - if [ -d .eggs ]; then echo "$(ls -d .eggs/*/) downloaded by build, update build environment" >&2; fi
+  allow_failure: true
+
+
+.test:
+  stage: test
+  script:
+    - py.test -r w --flakes kwant --junitxml=tests.xml --durations=10
+  artifacts:
+    reports:
+      junit: tests.xml
+
+.coverage:
+  stage: test
+  script:
+    - py.test -r w --cov=kwant --cov-report term --cov-report html --flakes kwant --junitxml=tests.xml --durations=10
+  artifacts:
+    paths:
+      - htmlcov
+    reports:
+      junit: tests.xml
+
+
+test:stable:
+  extends:
+    - .test
+    - .stable-env
+  dependencies:
+    - build:stable
+
+test:no-extras:
+  extends:
+    - .test
+    - .no-extras-env
+  dependencies:
+    - build:no-extras
+
+test:ubuntu:
+  extends:
+    - .test
+    - .ubuntu-env
+  dependencies:
+    - build:ubuntu
+
+test:debian:
+  extends:
+    - .test
+    - .debian-env
+  dependencies:
+    - build:debian
+
+test:latest:
+  extends:
+    - .test
+    - .latest-env
+  dependencies:
+    - build:latest
+
+test:bleeding-edge:
+  extends:
+    - .test
+    - .bleeding-edge-env
+  dependencies:
+    - build:bleeding-edge
+  only:
+    - schedules
+  allow_failure: true
+
+test:python-mumps:
+  extends:
+    - .test
+    - .latest-env
+  dependencies:
+    - build:latest
+  script:
+    - micromamba install -y -c conda-forge python-mumps
+    - py.test -r w --flakes kwant --junitxml=tests.xml --durations=10
+
+coverage:latest:
+  extends:
+    - .coverage
+    - .latest-env
+  dependencies:
+    - build:latest
+  only:
+    - schedules
+
+## Documentation building
+
+build documentation:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - python -c 'from matplotlib import pyplot'  # Pre-generate font cache
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc clean; make -C doc html SPHINXOPTS='-A website_deploy=True -n -D jupyter_execute_default_kernel=kwant-latest' SOURCE_LINK_TEMPLATE="$CI_PROJECT_URL"/blob/\$\$r/\$\$f
+  artifacts:
+    paths:
+      - doc/build/html/
+    expire_in: 1 month
+
+build PDF documentation:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - python -c 'from matplotlib import pyplot'  # Pre-generate font cache
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc latex SPHINXOPTS='-n -D jupyter_execute_default_kernel=kwant-latest'
+    - cd doc/build/latex
+    - make all-pdf
+  artifacts:
+    paths:
+      - doc/build/latex/kwant.pdf
+    expire_in: 1 month
+
+check for broken links in doc:
+  extends: .latest-env
+  dependencies:
+    - build:latest
+  stage: test
+  script:
+    - pip install --editable .  # Makefile executes from folders
+    - pip install ipykernel  # Temporary, should be removed after a jupyter-sphinx feedstock update.
+    - python -m ipykernel install --user --name kwant-latest  # Register the kernel
+    - make -C doc linkcheck SPHINXOPTS='-n -D jupyter_execute_default_kernel=kwant-latest'
+  allow_failure: true
+
+
+## Upload coverage reports and dev documentation
+
+upload coverage:
+  stage: deploy
+  only:
+    - schedules
+  dependencies:
+    - coverage:latest
+  environment:
+    name: coverage/$CI_COMMIT_REF_NAME
+    url: https://kwant-project.org/coverage/$CI_COMMIT_REF_SLUG
+    on_stop: remove_coverage
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - mv htmlcov $CI_COMMIT_REF_SLUG
+    - rsync -rlv -e "$SSH_COMMAND" --delete --relative $CI_COMMIT_REF_SLUG kwant@kwant-project.org:coverage/
+
+
+remove_coverage:
+  stage: deploy
+  only:
+    - branches@kwant/kwant
+  when: manual
+  environment:
+    name: coverage/$CI_COMMIT_REF_NAME
+    action: stop
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - mkdir empty/
+    - rsync -rlv -e "$SSH_COMMAND" --delete empty/ kwant@kwant-project.org:coverage/$CI_COMMIT_REF_SLUG
+
+
+upload documentation to the test server:
+  stage: deploy
+  environment:
+    name: docs review/$CI_COMMIT_REF_NAME
+    url: https://test.kwant-project.org/doc/$CI_COMMIT_REF_SLUG
+    on_stop: remove_docs
+  only:
+    - branches@kwant/kwant
+  script:
+    - eval $(ssh-agent -s)
+    - echo $TEST_WEBSITE_KEY | base64 -d | ssh-add -
+    - rsync -rlv -e "$SSH_COMMAND" --delete doc/build/html/* kwant2@test.kwant-project.org:doc/$CI_COMMIT_REF_SLUG
+
+
+remove_docs:
+  stage: deploy
+  when: manual
+  only:
+    - branches@kwant/kwant
+  environment:
+    name: docs review/$CI_COMMIT_REF_NAME
+    action: stop
+  script:
+    - eval $(ssh-agent -s)
+    - echo $TEST_WEBSITE_KEY | base64 -d | ssh-add -
+    - mkdir empty
+    - rsync -arv -e "$SSH_COMMAND" --delete empty/ kwant2@test.kwant-project.org:doc/$CI_COMMIT_REF_SLUG/
+
+
+upload dev version docs:
+  stage: deploy
+  environment:
+    name: production
+    url: https://kwant-project.org/doc/dev
+  rules:
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH && $CI_PROJECT_PATH == "kwant/kwant"
+  script:
+    - eval $(ssh-agent -s)
+    - echo $MASTER_WEBSITE_KEY | base64 -d | ssh-add -
+    - rsync -rlv -e "$SSH_COMMAND" --delete doc/build/html/* kwant@kwant-project.org:doc/dev
+
+
+## Build documentation for tagged releases
+
+.tagged-version:
+    only:
+       - /^v[0-9]+\.[0-9]+.[0-9]+$/@kwant/kwant
+
+gather release artifacts:
+  extends: .tagged-version
+  stage: release
+  script:
+    - ./setup.py sdist
+    - mkdir docs
+    - mv doc/build/latex/kwant.pdf docs/kwant-doc-${CI_COMMIT_TAG//v}.pdf
+    - mv doc/build/html docs/html
+    - zip -r docs/kwant-doc-${CI_COMMIT_TAG//v}.zip docs/html
+  artifacts:
+    paths:
+      - docs
+      - dist

.gitlab/issue_templates/release.md

+# Release %vX.Y.Z **UPDATE THIS**
+
+This is a checklist based on the [release document](RELEASE.rst); consult it for more details.
+
+## Preflight checks
+
+- [ ] All the issues from this milestone are resolved
+- [ ] Ensure that tests pass on [main](https://gitlab.kwant-project.org/kwant/kwant/tree/main) branch
+- [ ] Documentation looks correct https://test.kwant-project.org/doc/main
+- [ ] [Whatnew](doc/source/pre/whatsnew) is up to date
+- [ ] `AUTHORS.rst` and `.mailmap` are up to date (run `git shortlog -s | sed -e "s/^ *[0-9\t ]*//"| xargs -i sh -c 'grep -q "{}" AUTHORS.rst || echo "{}"'`)
+
+## Make a release, but do not publish it yet
+
+- [ ] Tag the release
+- [ ] Build the source tarball and inspect it
+- [ ] Build the documentation
+
+## Test packaging
+
+These steps may be done in parallel
+
+### Debian
+
+- [ ] Follow the steps for building the Debian packages from [RELEASE.rst](RELEASE.rst)
+
+### Conda
+
+- [ ] Publish the release candidate source tarball "somewhere on the internet" (SOTI)
+- [ ] open a PR to the [conda-forge/kwant-feedstock](https://github.com/conda-forge/kwant-feedstock/) repo on Github. Make sure to mark the PR as WIP so that it doesn't get merged in accidentally
+    - [ ] set the upstream tarball URL (in meta.yaml) to SOTI
+    - [ ] update the tarball hash in meta.yaml
+- [ ] See if the package builds
+
+## Publish the release
+- [ ] push the tag
+- [ ] upload the source tarball to PyPI
+- [ ] upload the source tarball to the Kwant website
+- [ ] publish the debian packages
+- [ ] publish the ubuntu packages
+- [ ] create a new version of the Kwant conda-forge feedstock, and open a pull request to upstream
+- [ ] upload the documentation to the Kwant website
+- [ ] update the Kwant website to say that Conda is the preferred way to install Kwant on Windows
+
+## Announce the release
+- [ ] Write a short post summarizing the highlights on the Kwant website
+- [ ] post to the Kwant mailing list
+
+## Working towards next release
+- [ ] add a whatsnew file for the next release
+- [ ] tag this release with an `a0` suffix
+- [ ] push this tag to the official Kwant repository
+- [ ] create a milestone for the next release

.mailmap

+Thomas Kloss <kloss@itp.uni-frankfurt.de>
+<joseph@weston.cloud> <joseph.weston08@gmail.com>
+<joseph@weston.cloud> <joseph.weston@cea.fr>
+<joseph@weston.cloud> <me@josephweston.org>
+<joseph@weston.cloud> <v-josewe@microsoft.com>
+Tómas Örn Rosdahl <torosdahl@gmail.com>
+<slavoutich@ostroukh.me> <ostroukh@lorentz.leidenuniv.nl>
+<m.t.wimmer@tudelft.nl> <wimmer@lorentz.leidenuniv.nl>
+Dániel Varjas <dvarjas@gmail.com>
+Pablo Pérez Piskunow <pablo.perez.piskunow@gmail.com>
+Michał Nowak <albeercik@gmail.com>
+Paul Clisson <clissonpaul@gmail.com>
+Jörg Behrmann <behrmann@physik.fu-berlin.de>
+Rafał Skolasiński <r.j.skolasinski@gmail.com>

AUTHORS.rst

@@ -2,40 +2,55 @@
 Authors of Kwant
 ================
 
-The principal developers of Kwant are
-
-* Christoph W. Groth (INAC/CEA Grenoble)
-* Michael Wimmer (TU Delft)
-* Anton R. Akhmerov (TU Delft)
-* Xavier Waintal (INAC/CEA Grenoble)
-
-The authors can be reached at authors@kwant-project.org.
+The Kwant authors can be reached at authors@kwant-project.org.
 
-Other contributors to Kwant include
+The principal developers of Kwant are
 
-* Mathieu Istas (INAC/CEA Grenoble)
-* Daniel Jaschke (INAC/CEA Grenoble)
+* `Christoph Groth <mailto:christoph.groth@cea.fr>`_ (CEA Grenoble)
+* `Michael Wimmer <https://michaelwimmer.org>`_ (TU Delft)
+* `Anton Akhmerov <https://antonakhmerov.org>`_ (TU Delft)
+* `Xavier Waintal <https://www.pheliqs.fr/en/Pages/Portrait/Xavier-Waintal.aspx>`_ (CEA Grenoble)
+* `Joseph Weston <https://joseph.weston.cloud>`_ (TU Delft)
+
+Contributors to Kwant include
+
+* Jörg Behrmann (FU Berlin)
+* Pierre Carmier (CEA Grenoble)
+* Paul Clisson (CEA Grenoble)
+* `Dennis Heffels <mailto:d.heffels@fz-juelich.de>`_ (FZJ PGI-9)
+* Mathieu Istas (CEA Grenoble)
+* Daniel Jaschke (CEA Grenoble)
+* Thomas Kloss (CEA Grenoble)
+* Kelvin Loh (TNO)
+* Bas Nijholt (TU Delft)
 * Michał Nowak (TU Delft)
 * Viacheslav Ostroukh (Leiden University)
-* Adrien Sorgniard (INAC/CEA Grenoble)
-* Joseph Weston (INAC/CEA Grenoble)
+* Pablo Pérez Piskunow (TU Delft)
+* Tómas Örn Rosdahl (TU Delft)
+* Sebastian Rubbert (TU Delft)
+* Rafał Skolasiński (TU Delft)
+* Adrien Sorgniard (CEA Grenoble)
+* Dániel Varjas (TU Delft)
+* Kostas Vilkelis (TU Delft)
 
 We thank Christoph Gohlke for the creation of installers for Microsoft Windows.
 
-`CEA <http://cea.fr>`_ is the French Commissariat à l'énergie atomique et aux
+`CEA <https://www.cea.fr>`_ is the French Commissariat à l'énergie atomique et aux
 énergies alternatives.  The CEA is the copyright holder for the contributions of
 C. W. Groth, X. Waintal, and its other employees involved in Kwant.
 
 To find out who wrote a certain part of Kwant, please use the "blame" feature of
-`Git <http://git-scm.com/>`_, the version control system.
+`Git <https://git-scm.com/>`_, the version control system.
 
 
 Funding
 -------
 
-During the development of Kwant 1.0, A. R. Akhmerov and M. Wimmer were supported
-by the Dutch Science Foundation NWO/FOM and by the ERC Advanced Investigator
-Grant of C. W. J. Beenakker who enthousiastically supported this project.
-A. R. Akhmerov was partially supported by a Lawrence Golub fellowship.
-C. W. Groth and X. Waintal were supported by the ERC Consolidator Grant MesoQMC.
-X. Waintal also acknowledges support from the STREP ConceptGraphene.
+Research related to Kwant was funded by
+
+* the US Office of Naval Research,
+* the European Research Council,
+* the Netherlands Organisation for Scientific Research NWO (formerly NWO/FOM).
+* the French National Agency for Research (ANR)
+* the Future and Emerging Technologies (FET) & Information and Communication Technologies (ICT) actions
+* Lawrence Golub fellowship

CITING.rst

@@ -15,7 +15,7 @@ cite the main paper that introduces Kwant:
   C. W. Groth, M. Wimmer, A. R. Akhmerov, X. Waintal,
   *Kwant: a software package for quantum transport*,
   `New J. Phys. 16, 063065 (2014)
-  <http://iopscience.iop.org/1367-2630/16/6/063065/article>`_.
+  <https://doi.org/10.1088/1367-2630/16/6/063065>`_.
 
 
 Other references we ask you to consider
@@ -26,7 +26,7 @@ also cite the upcoming paper that describes the relevant algorithms. The
 reference will also be added here once it is available.
 
 Kwant owes much of its current performance to the use of the `MUMPS
-<http://graal.ens-lyon.fr/MUMPS/>`_ library for solving systems of sparse linear
+<https://graal.ens-lyon.fr/MUMPS/>`_ library for solving systems of sparse linear
 equations.  If you have done high-performance calculations, we suggest citing
 
   P. R. Amestoy, I. S. Duff, J. S. Koster, J. Y. L’Excellent, SIAM. J. Matrix

CONTRIBUTE.rst

@@ -4,11 +4,8 @@ Contributing to Kwant and reporting problems
 
 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.  Please see the `Kwant website
-<http://kwant-project.org/community>`_ for information on how to get in touch
-with the Kwant community.
+set of concepts. 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. Please see the
+`"Contributing" page <https://kwant-project.org/contribute>`_ of the Kwant
+website for more information.

INSTALL.rst

@@ -4,7 +4,7 @@ Installation of Kwant
 
 Ready-to-use Kwant packages are available for many platforms (like GNU/Linux,
 Mac OS X, Microsoft Windows).  See the `installation page of the Kwant website
-<http://kwant-project.org/install>`_ for instructions on how to install Kwant
+<https://kwant-project.org/install>`_ for instructions on how to install Kwant
 on your platform.  This is the recommended way for new users.
 
 The remainder of this section documents how to build Kwant from source.  This
@@ -15,35 +15,46 @@ information is mostly of interest to contributors and packagers.
 Generic instructions
 ********************
 
+Obtaining the source code
+=========================
+
+Source distributions of Kwant (and Tinyarray) are available at the `downloads
+section of the Kwant website <https://downloads.kwant-project.org/kwant/>`_ as well
+as `PyPI <https://pypi.org/project/kwant>`_.  The sources may be also
+cloned directly from the `official Kwant git repository
+<https://gitlab.kwant-project.org/kwant/kwant>`_.
+
+
 Prerequisites
 =============
 
 Building Kwant requires
- * `Python <http://python.org>`_ 3.4 or above (Kwant 1.1 is the last version to
-   support Python 2),
- * `SciPy <http://scipy.org>`_ 0.9 or newer,
- * `LAPACK <http://netlib.org/lapack/>`_ and `BLAS <http://netlib.org/blas/>`_,
+ * `Python <https://www.python.org/>`_ 3.8 or above,
+ * `NumPy <https://numpy.org/>`_ 1.18.0 or newer,
+ * `SciPy <https://www.scipy.org/>`_ 1.3.0 or newer,
+ * `LAPACK <https://netlib.org/lapack/>`_ and `BLAS <https://netlib.org/blas/>`_,
    (For best performance we recommend the free `OpenBLAS
-   <http://xianyi.github.com/OpenBLAS/>`_ or the nonfree `MKL
-   <http://software.intel.com/en-us/intel-mkl>`_.)
- * `Tinyarray <https://gitlab.kwant-project.org/kwant/tinyarray>`_, a NumPy-like
-   Python package optimized for very small arrays,
+   <https://www.openblas.net/>`_ or the nonfree `MKL
+   <https://www.intel.com/content/www/us/en/developer/tools/oneapi/onemkl.html>`_.)
+ * `Tinyarray <https://gitlab.kwant-project.org/kwant/tinyarray>`_ 1.2.2 or newer,
+a NumPy-like Python package optimized for very small arrays,
  * An environment which allows to compile Python extensions written in C and
    C++.
 
 The following software is highly recommended though not strictly required:
- * `matplotlib <http://matplotlib.sourceforge.net/>`_ 1.1 or newer, for Kwant's
-   plotting module and the tutorial,
- * `MUMPS <http://graal.ens-lyon.fr/MUMPS/>`_, a sparse linear algebra library
+ * `matplotlib <https://matplotlib.org/>`_ 3.2.2 or newer, for the module `kwant.plotter` and the tutorial,
+ * `SymPy <https://sympy.org/>`_ 1.5.1 or newer, for the subpackage `kwant.continuum`.
+ * `Qsymm <https://pypi.org/project/qsymm/>`_ 1.2.6 or newer, for the subpackage `kwant.qsymm`.
+ * `MUMPS <https://mumps-solver.org/>`_, a sparse linear algebra library
    that will in many cases speed up Kwant several times and reduce the memory
    footprint.  (Kwant uses only the sequential, single core version
    of MUMPS.  The advantages due to MUMPS as used by Kwant are thus independent
    of the number of CPU cores of the machine on which Kwant runs.)
- * The `nose testing framework <http://nose.readthedocs.org/>`_ for running the
+ * The `py.test testing framework <https://docs.pytest.org/>`_ 3.3.2 or newer for running the
    tests included with Kwant.
 
 In addition, to build a copy of Kwant that has been checked-out directly from
-version control, you will also need `Cython <http://cython.org/>`_ 0.22 or
+version control, you will also need `Cython <https://cython.org/>`_ 3.0 or
 newer.  You do not need Cython to build Kwant that has been unpacked from a
 source .tar.gz-file.
 
@@ -51,9 +62,8 @@ source .tar.gz-file.
 Building and installing Kwant
 =============================
 
-Kwant can be built and installed following the `usual Python conventions
-<http://docs.python.org/install/index.html>`_ by running the following commands
-in the root directory of the Kwant distribution. ::
+Kwant can be built and installed by running the following commands in the root
+directory of the Kwant distribution. ::
 
     python3 setup.py build
     python3 setup.py install
@@ -74,54 +84,70 @@ cythonization is disabled when building not from git.  If ever necessary, this
 default can be overridden by giving the ``--cython`` option to setup.py.)
 
 
+.. _build-configuration:
+
 Build configuration
 ===================
 
-The setup script of Kwant has to know how to link against LAPACK & BLAS, and,
-optionally, MUMPS.  By default it will assume that LAPACK and BLAS can be found
-under their usual names.  MUMPS will be not linked against by default, except
-on Debian-based systems when the package ``libmumps-scotch-dev`` is installed.
-
-All these settings can be configured by creating/editing the file
-``build.conf`` in the root directory of the Kwant distribution.  This
-configuration file consists of sections, one for each dependency, led by a
-[dependency-name] header and followed by name = value entries.  Possible names
-are keyword arguments for ``distutils.core.Extension`` (For a complete list,
-see its `documentation
-<http://docs.python.org/3/distutils/apiref.html#distutils.core.Extension>`_).
+Kwant contains several extension modules.  The compilation and linking of these
+modules can be configured by editing a build configuration file.  By default,
+this file is ``build.conf`` in the root directory of the Kwant distribution.  A
+different path may be provided using the ``--configfile=PATH`` option.
+
+This configuration file consists of
+sections, one for each extension module that is contained in Kwant, led by a
+``[section name]`` header and followed by ``key = value`` lines.
+
+The sections bear the names of the extension modules, for example
+``[kwant.operator]``.  There can be also a
+``[DEFAULT]`` section that provides default values for all extensions, also
+those not explicitly present in the file.
+
+Possible keys are the keyword arguments for ``setuptools.Extension`` (For a
+complete list, see its `documentation
+<https://setuptools.pypa.io/en/latest/userguide/ext_modules.html>`_).
 The corresponding values are whitespace-separated lists of strings.
 
-The two currently possible sections are [lapack] and [mumps].  The former
-configures the linking against LAPACK _AND_ BLAS, the latter against MUMPS
-(without LAPACK and BLAS).
+Example ``build.conf`` for compiling Kwant with C assertions and Cython's line
+trace feature::
+
+    [DEFAULT]
+    undef_macros = NDEBUG
+    define_macros = CYTHON_TRACE=1
+
+Kwant can optionally be linked against MUMPS.  The main
+application of build configuration is adopting the build process to the various
+deployments of MUMPS. MUMPS will be not linked
+against by default, except on Debian-based systems when the package
+``libmumps-scotch-dev`` is installed.
+
+The section ``[kwant.linalg._mumps]`` may be used to adapt the build process.
+(For simplicity and backwards compatibility, ``[mumps]`` is an aliases for the above.)
+
 
 Example ``build.conf`` for linking Kwant against a self-compiled MUMPS, `SCOTCH
-<http://www.labri.fr/perso/pelegrin/scotch/>`_ and `METIS
+<https://www.labri.fr/perso/pelegrin/scotch/>`_ and `METIS
 <http://glaros.dtc.umn.edu/gkhome/metis/metis/overview>`_::
 
     [mumps]
     libraries = zmumps mumps_common pord metis esmumps scotch scotcherr mpiseq gfortran
 
-Example ``build.conf`` for linking Kwant with Intel MKL.::
-
-    [lapack]
-    libraries = mkl_intel_lp64 mkl_sequential mkl_core mkl_def
-    library_dirs = /opt/intel/mkl/lib/intel64
-    extra_link_args = -Wl,-rpath=/opt/intel/mkl/lib/intel64
-
 The detailed syntax of ``build.conf`` is explained in the `documentation of
 Python's configparser module
-<http://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
+<https://docs.python.org/3/library/configparser.html#supported-ini-file-structure>`_.
 
 
 Building the documentation
 ==========================
 
 To build the documentation, the `Sphinx documentation generator
-<http://sphinx.pocoo.org/>`_ is required with ``numpydoc`` extension
-(version 0.5 or newer).  If PDF documentation is to be built, the tools
-from the `libRSVG <http://live.gnome.org/LibRsvg>`_ (Debian/Ubuntu package
-``librsvg2-bin``) are needed to convert SVG drawings into the PDF format.
+<https://www.sphinx-doc.org/en/stable/>`_ is required with ``numpydoc`` extension
+(version 0.5 or newer), as well as ``jupyter-sphinx`` (version 0.2 or newer).
+If PDF documentation is to be built, the tools
+from the `libRSVG <https://wiki.gnome.org/action/show/Projects/LibRsvg>`_
+(Debian/Ubuntu package ``librsvg2-bin``) and a Sphinx extension
+``sphinxcontrib-svg2pdfconverter`` are needed to convert SVG drawings into the
+PDF format.
 
 As a prerequisite for building the documentation, Kwant must have been built
 successfully using ``python3 setup.py build`` as described above (or Kwant must
@@ -135,7 +161,6 @@ Because of some quirks of how Sphinx works, it might be necessary to execute
 done, Sphinx may mistakenly use PNG files for PDF output or other problems may
 appear.
 
-
 ****************************
 Hints for specific platforms
 ****************************
@@ -152,7 +177,7 @@ root.
 1. Install the required packages.  On Debian-based systems like Ubuntu this can
    be done by running the command ::
 
-       sudo apt-get install python-dev python-scipy python-matplotlib python-nose g++ gfortran libopenblas-dev liblapack-dev libmumps-scotch-dev
+       sudo apt-get install python3-dev python3-setuptools python3-scipy python3-matplotlib python3-pytest python3-sympy g++ gfortran libmumps-scotch-dev
 
 2. Unpack Tinyarray, enter its directory. To build and install, run ::
 
@@ -168,78 +193,6 @@ By default the package will be installed under ``/usr/local``.  Run ``python3
 setup.py --help install`` for installation options.
 
 
-Mac OS X: MacPorts
-==================
-
-The following instructions are valid for Kwant 1.1 with Python 2.7.  They need
-to be updated for Kwant 1.2.  (Help is welcome.)
-
-The required dependencies of Kwant are best installed with one of the packaging
-systems. Here we only consider the case of `MacPorts
-<http://www.macports.org>`_ in detail. Some remarks for homebrew are given
-below.
-
-1. Install a recent version of MacPorts, as explained in the `installation
-   instructions of MacPorts <http://www.macports.org/install.php>`_.  `The
-   MacPorts section of the Kwant website
-   <http://kwant-project.org/install#mac-os-x-macports>`_ may be also of
-   interest.  (Note that it describes how to install Kwant using a ports file,
-   while the aim here is to install from source manually.)
-
-2. Install the required dependencies::
-
-       sudo port install gcc47 python27 py27-numpy py27-scipy py27-matplotlib mumps_seq
-       sudo port select --set python python27
-
-3. Unpack Tinyarray, enter its directory, build and install::
-
-       python setup.py build
-       sudo python setup.py install
-
-p5. Unpack Kwant, go to the Kwant directory, and edit ``build.conf`` to read::
-
-       [lapack]
-       extra_link_args = -Wl,-framework -Wl,Accelerate
-       [mumps]
-       include_dirs = /opt/local/include
-       library_dirs = /opt/local/lib
-       libraries = zmumps_seq mumps_common_seq pord_seq esmumps scotch scotcherr mpiseq gfortran
-
-6. Then, build and install Kwant. ::
-
-       CC=gcc-mp-4.7 LDSHARED='gcc-mp-4.7 -shared -undefined dynamic_lookup' python setup.py build
-       sudo python setup.py install
-
-You might note that installing Kwant on Mac OS X is somewhat more involved than
-installing on Linux. Part of the reason is that we need to mix Fortran and C
-code in Kwant: While C code is usually compiled using Apple compilers,
-Fortran code must be compiled with the Gnu Fortran compiler (there is
-no Apple Fortran compiler). For this reason we force the Gnu compiler suite
-with the environment variables ``CC`` and ``LDSHARED`` as shown above.
-
-
-Mac OS X: homebrew
-==================
-
-The following instructions are valid for Kwant 1.1 with Python 2.7.  They need
-to be updated for Kwant 1.2.  (Help is welcome.)
-
-It is also possible to build Kwant using homebrew. The dependencies can be
-installed as ::
-
-    brew install gcc python
-    brew tap homebrew/science
-    brew tap homebrew/python
-    brew tap kwant-project/kwant
-    pip install nose six
-    brew install numpy scipy matplotlib
-
-Note that during the installation you will be told which paths to add when you
-want to compile/link against scotch/metis/mumps; you need to add these to the
-build.conf file. Also, when linking against MUMPS, one needs also to link
-against METIS (in addition to the libraries needed for MacPorts).
-
-
 Microsoft Windows
 =================
 

README.rst

@@ -28,14 +28,11 @@ Kwant can calculate
 Other computations involving tight-binding Hamiltonians can be implemented
 easily.
 
-See the `Kwant web site <http://kwant-project.org/>`_ for the latest stable
+See the `Kwant website <https://kwant-project.org/>`_ for the latest stable
 version.  The current development version is available via the `Kwant gitlab
 instance <https://gitlab.kwant-project.org/kwant/kwant>`_.  Contributions are
 welcome.
 
-A `mailing list <http://kwant-project.org/community>`_ exists for general
+A `mailing list <https://kwant-project.org/community>`_ exists for general
 discussions related to Kwant.  Please report bugs and other issues using the
 `issue tracker <https://gitlab.kwant-project.org/kwant/kwant/issues>`_.
-
-See also in this directory: `<INSTALL.rst>`_, `<LICENSE.rst>`_, `<AUTHORS.rst>`_,
-`<CITING.rst>`_, `<CONTRIBUTE.rst>`_.

RELEASE.rst

+Making a Kwant release
+======================
+
+This document guides a contributor through creating a release of Kwant.
+
+Create a release issue
+######################
+
+Use the correct `issue template <gitlab.kwant-project.org/kwant/kwant/issues/new?issuable_template=release>`_, adjust it if necessary.
+
+Preflight checks
+################
+
+The following checks should be made *before* tagging the release.
+
+
+Check that all issues are resolved
+----------------------------------
+
+Check that all the issues and merge requests for the appropriate
+`milestone <https://gitlab.kwant-project.org/kwant/kwant/milestones>`_
+have been resolved. Any unresolved issues should have their milestone
+bumped.
+
+
+Ensure that all tests pass
+--------------------------
+
+For major and minor releases we will be tagging the ``master`` branch.
+For patch releases, the ``stable`` branch.
+This should be as simple as verifying that the latest CI pipeline succeeded,
+however in ``stable`` branch also manually trigger CI task of building the
+conda package and verify that it, too, succeeds.
+
+
+Inspect the documentation
+-------------------------
+
+If the CI pipeline succeeded, then the latest docs should be available at:
+
+    https://test.kwant-project.org/doc/<branch name>
+
+Check that there are no glaring deficiencies.
+
+
+Update the ``whatsnew`` file
+----------------------------
+
+For each new minor release, check that there is an appropriate ``whatsnew`` file
+in ``doc/source/pre/whatsnew``.  This should be named as::
+
+    <major>.<minor>.rst
+
+and referenced from ``doc/source/pre/whatsnew/index.rst``.  It should contain a
+list of the user-facing changes that were made in the release. With any luck
+this file will have been updated at the same time as a feature was implemented,
+if not then you can see what commits were introduced since the last release using
+``git log``. You can also see what issues were assigned to the release's
+milestones and get an idea of what was introduced from there.
+
+Starting with Kwant 1.4, we also mention user-visible changes in bugfix
+releases in the whatsnew files.
+
+
+Verify that ``AUTHORS.rst`` and ``.mailmap`` are up-to-date
+-----------------------------------------
+
+The following command shows if there are any committers that are missing from
+``AUTHORS.rst``::
+
+  git shortlog -s | sed -e "s/^ *[0-9\t ]*//"| xargs -i sh -c 'grep -q "{}" AUTHORS.rst || echo "{}"'
+
+If it outputs anything, then either add the new contributors to the list, or add
+new identities of old contributors to the ``.mailmap``
+
+Make a release, but do not publish it yet
+#########################################
+
+Various problems can surface only during the process of preparing a release and
+make it necessary to fix the codebase.  It would be a pity to have to succeed
+the freshly released version by a minor release just to correct a glitch that
+was detected too late.  Therefore it is a good idea to pursue the release as
+far as possible without announcing it, such that it can be undone and corrected
+if necessary.  In the past tests that failed on the x86-32 architecture and
+wrongly declared dependencies have been detected in this way.
+
+
+Tag the release
+---------------
+
+Make an *annotated*, *signed* tag for the release. The tag must have the name::
+
+    git tag -s v<version> -m "version <version>"
+
+Be sure to respect the format of the tag name (leading "v", e.g. "v1.2.3").
+The tag message format is the one that has been used so far.
+
+Do *not* yet push the tag anywhere; it might have to be undone!
+
+
+Build a source tarball and inspect it
+-------------------------------------
+
+    ./setup.py sdist
+
+This creates the file dist/kwant-<version>.tar.gz.  It is a good idea to unpack it
+in /tmp and inspect that builds in isolation and that the tests run::
+
+    cd /tmp
+    tar xzf ~/src/kwant/dist/kwant-<version>.tar.gz
+    cd kwant-<version>
+    ./setup.py build
+    ./setup.py build_ext -i
+    py.test
+
+
+Build the documentation
+-----------------------
+Building the documentation requires 'sphinx' and a Latex installation.
+First build the HTML and PDF documentation::
+
+    ./setup.py build
+    make -C doc realclean
+    make -C doc html latex
+    make -C doc/build/latex all-pdf
+
+Then create a zipped version of the HTML documentation and name the PDF
+consistently, storing them, for example, in the "dist" directory along with the
+source tarballs::
+
+    version=$(git describe | sed 's/^v//') # Assumes that we are on a tag.
+    ln -s `pwd`/doc/build/html /tmp/kwant-doc-$version
+    (cd /tmp/; zip -r kwant-doc-$version.zip kwant-doc-$version)
+    mv /tmp/kwant-doc-$version.zip dist
+    mv doc/build/latex/kwant.pdf dist/kwant-doc-$version.pdf
+
+Finally, rebuild the documentation for the website (including the web analysis javascript code)::
+
+    make -C doc html SPHINXOPTS='-A website_deploy=True -n -W'
+
+
+Clone the repository of the Kwant Debian package
+------------------------------------------------
+
+This step needs to be performed only once.  The cloned repository can be reused
+for subsequent releases.
+
+Clone the "kwant-debian" repository and go into its root directory.  If you
+keep the Kwant source in "src/kwant", a good location for the Debian package
+repository is "src/debian/kwant".  The packaging process creates many files
+that are placed into the parent directory of the packaging repository, hence
+having an additional directory level ("src/debian") is a good way to keep these
+files separate::
+
+    mkdir debian
+    cd debian
+    git clone ssh://git@gitlab.kwant-project.org:443/kwant/debian-kwant.git kwant
+    cd kwant
+
+Create a local upstream branch::
+
+    git branch upstream origin/upstream
+
+Add a remote for the repository that contains the previously created tag::
+
+    git remote add upstream_repo ~/src/kwant
+
+Make sure that::
+
+    git config --get user.name
+    git config --get user.email
+
+show correct information.
+
+
+Release a new version of the Kwant Debian package
+-------------------------------------------------
+
+Fetch packaging work (from origin) and the git tag created above (from
+upstream_repo) into the packaging repo::
+
+    git fetch --all
+
+Make sure that the branches ``master`` and ``upstream`` are up-to-date::
+
+    git checkout upstream
+    git merge --ff-only origin/upstream
+    git checkout master
+    git merge --ff-only origin/master
+
+Debian packages may include "quilt" patches that are applied on top of the
+pristine tarball.  The tool `gbp pq` manages these patches as a git branch
+``patch-queue/master.  Execute the following commands to (re)create
+that branch based on the patches in ``debian/patches``::
+
+    gbp pq --force import
+    git checkout master
+
+Now it is time to import the new source code.  There are two options.  If, as
+recommended above, the tarball of the new version has not been made public yet,
+it must be imported as follows::
+
+    gbp import-orig ~/src/kwant/dist/kwant-<version>.tar.gz
+
+Alternatively, the following commands will import the newest version from PyPI::
+
+    uscan --report      # This will report if a newer version exists on PyPI
+    gbp import-orig --uscan
+
+Now it is time to review the patch queue.  Rebase and checkout the ``patch-queue/master`` branch using::
+
+    gbp pq rebase
+
+As ususal, the rebase might require manual intervention.  Once done, review all
+the commits of the ``patch-queue/master`` branch.  Are all patches still
+needed, should any be removed?  When done (even if no changes were needed), recreate the files in ``debian/patches`` using::
+
+    gbp pq export
+
+If ``git diff`` reports any changes, be sure to commit them.
+
+Now is the right moment to verify and modify the packaging information inside
+the ``debian/`` directory.  For example, are the dependencies and versions
+stated in ``debian/control`` up-to-date?
+
+When all changes are commited, it is time to finalize by updating the Debian
+changelog file.  Add a point "New upstream release" if there was one, and
+describe any other changes to the Debian *packaging*::
+
+    DEBEMAIL=<your-email> gbp dch -R --commit --distribution testing
+
+Now verify that the package builds with::
+
+    git clean -i
+    gbp buildpackage
+
+This is *not* how the package should be built for distribution.  For that, see
+the following two sections.
+
+If problems surface that require changing the packaging, undo the changelog
+commit, modify the packaging, and re-iterate.  If the problems require fixing
+Kwant, you will have to go back all the way to recreating the source tarball.
+If the version to be packaged has been released publicly already, this will require a new bugfix version.
+
+
+Setup git-pbuilder to build Debian packages
+-------------------------------------------
+
+Pbuilder is a tool to build Debian packages in an isolated chroot.  This allows
+to verify that the package indeed only has the declared dependencies.  It also
+allows to cross-build packages for i386 on amd64.
+
+The following describes how to setup git-pbuilder, see also
+https://wiki.debian.org/git-pbuilder.  This procedure needs to be executed only
+once for a Debian system.
+
+Install the Debian package git-buildpackage.
+
+As root, add the following lines to /etc/sudoers or /etc/sudoers.d/local
+
+    Cmnd_Alias BUILD = /usr/sbin/cowbuilder
+
+and
+
+    user     ALL = SETENV: BUILD
+
+Now create pbuilder images.  In the following, replace ``<dist>`` by the
+current Debian testing codename, e.g. "buster"::
+
+    ARCH=i386 DIST=<dist> git-pbuilder create
+    ARCH=amd64 DIST=<dist> git-pbuilder create
+
+If the packages to be built have special dependencies, use the trick described in https://wiki.debian.org/git-pbuilder#Using_Local_Packages
+
+
+Build Kwant packages using git-pbuilder
+---------------------------------------
+
+Update the builder environment (again, replace ``<dist>`` with the name of the
+current Debian testing)::
+
+    ARCH=i386 DIST=<dist> git-pbuilder update
+    ARCH=amd64 DIST=<dist> git-pbuilder update
+
+Make sure that the working directory is completely clear::
+
+    git clean -id
+
+(Note that pytest has the nasty habit of creating a hidden ``.pytest_cache``
+directory which gitignores itself.  The above command will not delete this
+directory, but git-pbuilder will complain.)
+
+Now build the packages.  First the i386 package.  The option "--git-tag" tags
+and signs the tag if the build is successful.  In a second step, the package is
+built for amd64, but only the architecture-dependent files (not the
+documentation package)::
+
+    gbp buildpackage --git-pbuilder --git-arch=i386 --git-dist=<dist> --git-tag
+    gbp buildpackage --git-pbuilder --git-arch=amd64 --git-dist=<dist> --git-pbuilder-options='--binary-arch'
+
+Another example: build source package only::
+
+    gbp buildpackage --git-export-dir=/tmp -S
+
+
+Build backports for the current Debian stable
+---------------------------------------------
+
+Create a changelog entry for the backport::
+
+    DEBEMAIL=<your-email> dch --bpo
+
+As shown above, run ``git-pbuilder update`` for the appropriate distribution
+codename.
+
+Build backported packages::
+
+    gbp buildpackage --git-pbuilder --git-ignore-new --git-arch=i386 --git-dist=<dist>
+    gbp buildpackage --git-pbuilder --git-ignore-new --git-arch=amd64 --git-dist=<dist> --git-pbuilder-options='--binary-arch'
+
+Do not commit anything.
+
+
+Publish the release
+###################
+
+If the Debian packages build correctly that means that all tests pass both on
+i386 and amd64, and that no undeclared dependencies are needed.  We can be
+reasonably sure that the release is ready to be published.
+
+
+git
+---
+
+Push the tag to the official Kwant repository::
+
+    git push origin v<version>
+
+
+PyPI
+----
+
+Install `twine <https://pypi.org/project/twine>`_ and run the following
+(this requires a file ~/.pypirc with a valid username and password: ask
+Christoph Groth to add you as a maintainer on PyPI, if you are not already)::
+
+    twine upload -s dist/kwant-<version>.tar.gz
+
+It is very important that the tarball uploaded here is the same (bit-by-bit,
+not only the contents) as the one used for the Debian packaging.  Otherwise it
+will not be possible to build the Debian package based on the tarball from
+PyPI.
+
+
+Kwant website
+-------------
+
+The following requires ssh access to ``kwant-project.org`` (ask Christoph
+Groth). The tarball and its signature (generated by the twine command above) should be
+uploaded to the downloads section of the website::
+
+    scp dist/kwant-<version>.tar.gz* kwant:web/downloads/kwant
+
+
+Debian packages
+---------------
+
+Go to the Debian packaging repository and push out the changes::
+
+    git push --tags origin master upstream
+
+Now the Debian packages that we built previously need to be added to the
+repository of Debian packages on the Kwant website.  So far the full
+version of this repository is kept on Christoph Groth's machine, so these
+instructions are for reference only.
+
+Go to the reprepro repository directory and verify that the configuration file
+"conf/distributions" looks up-to-date.  It should look something like this (be
+sure to update the codenames and the versions)::
+
+    Origin: Kwant project
+    Suite: stretch-backports
+    Codename: stretch-backports
+    Version: 9.0
+    Architectures: i386 amd64 source
+    Components: main
+    Description: Unofficial Debian package repository of https://kwant-project.org/
+    SignWith: C3F147F5980F3535
+
+    Origin: Kwant project
+    Suite: testing
+    Codename: buster
+    Version: 10.0
+    Architectures: i386 amd64 source
+    Components: main
+    Description: Unofficial Debian package repository of https://kwant-project.org/
+    SignWith: C3F147F5980F3535
+
+If the config had to be updated execute::
+
+    reprepro --delete clearvanished
+    reprepro export
+    reprepro --delete createsymlinks
+
+In addition to the above, if distributions were removed from the
+configuration file the corresponding directories must be removed
+manually from under the `dists` subdirectory.
+
+Now the source and binary Debian packages can be added.  The last line has to
+be executed for all the .deb files and may be automated with a shell loop. (Be
+sure to use the appropriate <dist>: for the above configuratoin file either
+"testing" or "stretch-backports".)::
+
+    reprepro includedsc <dist> ../../src/kwant_<version>-1.dsc
+    reprepro includedeb <dist> python3-kwant_<version>-1_amd64.deb
+
+Once all the packages have been added, upload the repository::
+
+    rsync -avz --delete dists pool kwant-project.org:webapps/downloads/debian
+
+
+Ubuntu packages
+---------------
+
+Packages for Ubuntu are provided as a PPA (Personal Package Archive):
+https://launchpad.net/~kwant-project/+archive/ubuntu/ppa
+
+Make sure ~/.dput.cf has something like this::
+
+    [ubuntu-ppa-kwant]
+    fqdn = ppa.launchpad.net
+    method = ftp
+    incoming = ~kwant-project/ppa/ubuntu/
+    login = anonymous
+    allow_unsigned_uploads = 0
+
+We will also use the following script (prepare_ppa_upload)::
+
+    #!/bin/sh
+
+    if [ $# -eq 0 ]; then
+        echo -e "\nUsage: $(basename $0) lousy mourning2 nasty\n"
+        exit
+    fi
+
+    version=`dpkg-parsechangelog --show-field Version`
+    mv debian/changelog /tmp/changelog.$$
+
+    for release in $@; do
+        cp /tmp/changelog.$$ debian/changelog
+        DEBEMAIL=christoph.groth@cea.fr dch -b -v "$version~$release" -u low 'Ubuntu PPA upload'
+        sed -i -e "1,1 s/UNRELEASED/${release%[0-9]}/" debian/changelog
+        debuild -S -sa
+    done
+
+    mv /tmp/changelog.$$ debian/changelog
+
+Make sure that the Debian package builds correctly and go to its directory.
+
+Check https://wiki.ubuntu.com/Releases for the relevant releases (we want to
+provide packages at least for the current LTS release and the newer non-LTS
+releases) and execute::
+
+    prepare_ppa_upload <dist0> <dist1> <dist2>
+
+(if a second upload of the same Debian version is needed, something like "vivid2" instead of "vivid" can be used.)
+
+Now the changes files are "put" to start the build process on the PPA servers::
+
+    cd ..
+    dput ubuntu-ppa-kwant *~*.changes
+
+
+Clone the repository of the Kwant conda-forge package
+-----------------------------------------------------
+
+This step needs to be performed only once.  The cloned repository can be reused
+for subsequent releases.
+
+Clone the "Kwant feedstock" repository and go into its root directory.  If you
+keep the Kwant source in "src/kwant", a good location for the Conda package
+repository is "src/conda-forge/kwant"::
+
+    cd ~/src
+    mkdir conda-forge
+    cd conda-forge
+    git clone https://github.com/conda-forge/kwant-feedstock kwant
+    cd kwant
+
+Rename the default remote to ``upstream``::
+
+    git remote rename origin upstream
+
+
+Create a new version of the Kwant conda-forge package
+-----------------------------------------------------
+
+Edit the file ``recipe/meta.yml``. Correctly set the ``version``
+at the top of the file to the version of this release. Set the ``sha256``
+string in the ``source`` section near the top of the file to the SHA256 hash
+of the kwant source tarball that we previously created. You can find the
+SHA256 hash by running ``openssl sha256 <filename>`` on Linux and Mac OSX.
+
+Commit your changes.
+
+
+Conda forge
+-----------
+This step requires a GitHub account, as Conda forge packages are autobuilt
+from repositories hosted on GitHub.
+
+Fork the `Kwant feedstock <https://github.com/conda-forge/kwant-feedstock>`_
+repository and add your fork as a remote to the copy that you previously cloned::
+
+    cd ~/conda-forge/kwant
+    git remote add myfork https://github.com/<your-gh-username>/kwant-feedstock
+
+Push the changes that you previously commited to your fork::
+
+    git push myfork master
+
+Open a pull request to Kwant feedstock repository. Ask Bas Nijholt or
+Joseph Weston to review and accept the pull request.
+
+
+Documentation
+-------------
+The following requires ssh access to  ``kwant-project.org``.
+Ask Christoph Groth if you need to be granted access.
+
+Upload the zipped HTML and PDF documentation::
+
+    scp dist/kwant-doc-<version>.{zip,pdf} kwant:web/downloads/doc
+
+Upload the HTML documentation for the website::
+
+    rsync -rlv --delete doc/build/html/* kwant:web/main/doc/<short-version>
+
+where in the above ``<short-version>`` is just the major and minor version numbers.
+
+Finally, create symbolic links for the website::
+
+    ssh kwant
+    for e in zip pdf; do ln -sf kwant-doc-<version>.$e webapps/downloads/doc/latest.$e; done
+    ln -nsf <short-version> webapps/kwant/doc/<major>
+    exit
+
+
+Announce the release
+####################
+
+Write a short post summarizing the highlights of the release on the
+`Kwant website <https://gitlab.kwant-project.org/kwant/website>`, then
+post this to the mailing list kwant-discuss@kwant-project.org.
+
+
+Working towards the next release
+################################
+
+After finalizing a release, a new ``whatsnew`` file should be created for
+the *next* release, and this addition should be committed and tagged as::
+
+    <new major>.<new minor>.<new patch>a0
+
+This tag should be pushed to Kwant Gitlab, and a new milestone for the next
+release should be created.

check_whitespace

+#!/bin/sh
+
+! for f in $(git ls-files | grep -v \\.diff$); do
+    file $f | grep -q ' text' || continue
+    grep -q '[[:blank:]]$' $f && echo $f: trailing whitespace
+    tail -n1 $f | read -r _ || echo $f: no newline at end of file
+    tail -n1 $f | grep -q '^$' && echo $f: empty line at end of file
+done | grep . >&2

conftest.py

+# Copyright 2011-2018 Kwant authors.
+#
+# This file is part of Kwant.  It is subject to the license terms in the file
+# LICENSE.rst found in the top-level directory of this distribution and at
+# https://kwant-project.org/license.  A list of Kwant authors can be found in
+# the file AUTHORS.rst at the top-level directory of this distribution and at
+# https://kwant-project.org/authors.
+"""Pytest plugin to ignore packages that have uninstalled dependencies.
+
+This ignores packages on test collection, which is required when the
+tests reside in a package that itself requires the dependency to be
+installed.
+"""
+
+import importlib
+
+
+# map from subpackage to sequence of dependency module names
+subpackage_dependencies = {
+    'kwant/continuum': ['sympy'],
+    'kwant/tests/test_qsymm': ['qsymm', 'sympy'],
+}
+
+
+# map from subpackage to sequence of dependency modules that are not installed
+dependencies_not_installed = {}
+for package, dependencies in subpackage_dependencies.items():
+    not_installed = []
+    for dep in dependencies:
+        try:
+            importlib.import_module(dep)
+        except ImportError:
+            not_installed.append(dep)
+    if len(not_installed) != 0:
+        dependencies_not_installed[package] = not_installed
+
+
+def pytest_ignore_collect(path, config):
+    for subpackage, not_installed in dependencies_not_installed.items():
+        if subpackage in path.strpath:
+            print('ignoring {} because the following dependencies are not '
+                  'installed: {}'.format(subpackage, ', '.join(not_installed)))
+            return True

doc/Makefile

-# Makefile for Sphinx documentation
-
-# Copyright 2011-2013 Kwant authors.
+# Minimal makefile for Sphinx documentation
 #
-# This file is part of Kwant.  It is subject to the license terms in the file
-# LICENSE.rst found in the top-level directory of this distribution and at
-# http://kwant-project.org/license.  A list of Kwant authors can be found in
-# the file AUTHORS.rst at the top-level directory of this distribution and at
-# http://kwant-project.org/authors.
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
-SPHINXBUILD   = python3 -c 'import sys, sphinx; sys.exit(sphinx.main(sys.argv))'
-PAPER         =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
 BUILDDIR      = build
 
-# Internal variables.
-PAPEROPT_a4     = -D latex_paper_size=a4
-PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
-
-# We convert all SVG files to PDF for LaTeX output.  For HTML output, we don't
-# create PNGs but rather use the SVG files directly.
-IMAGESOURCES    = $(shell find source -name "*.svg")
-GENERATEDPDF    = $(patsubst %.svg,%.pdf,$(IMAGESOURCES))
-
-# Image generation from patched tutorial scripts
-#
-# As make does not support the generation of multiple targets by a single
-# invocation of a (non-implicit) rule, we use a trick: We pretend to be
-# generating a single (empty) flag file per invocation.  The image files are
-# generated as well, but only as side-effects.  Each flag file is used to
-# remember the time at which the corresponding image-generating script was run.
-# This works perfectly unless the actual output files are deleted without
-# deleting the corresponding flag file.
-SCRIPTS = $(patsubst source/images/%.diff,%,$(wildcard source/images/*.py.diff))
-FLAGS = $(patsubst %.py,source/images/.%_flag,$(SCRIPTS))
-
-.PHONY: help clean realclean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
-
+# Put it first so that "make" without argument is like "make help".
 help:
-	@echo "Please use \`make <target>' where <target> is one of"
-	@echo "  html      to make standalone HTML files"
-	@echo "  dirhtml   to make HTML files named index.html in directories"
-	@echo "  pickle    to make pickle files"
-	@echo "  json      to make JSON files"
-	@echo "  htmlhelp  to make HTML files and a HTML help project"
-	@echo "  qthelp    to make HTML files and a qthelp project"
-	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
-	@echo "  changes   to make an overview of all changed/added/deprecated items"
-	@echo "  linkcheck to check all external links for integrity"
-	@echo "  doctest   to run all doctests embedded in the documentation (if enabled)"
-	@echo
-	@echo "Append SPHINXOPTS='-A website_deploy=True' to include web analytics code."
-
-clean:
-	-rm -rf $(BUILDDIR)/* $(GENERATEDPDF)
-	-rm -rf source/reference/generated
-
-realclean: clean
-	-rm -f $(FLAGS)
-	-rm -f $(patsubst %,source/images/%,$(SCRIPTS))
-	-rm -f $(patsubst %.py,source/images/%_*.png,$(SCRIPTS))
-	-rm -f $(patsubst %.py,source/images/%_*.pdf,$(SCRIPTS))
-
-html:	$(FLAGS)
-	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-dirhtml: $(FLAGS)
-	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
-	@echo
-	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+.PHONY: help Makefile
 
-pickle: $(FLAGS)
-	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
-	@echo
-	@echo "Build finished; now you can process the pickle files."
-
-json:   $(FLAGS)
-	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
-	@echo
-	@echo "Build finished; now you can process the JSON files."
-
-htmlhelp: $(FLAGS)
-	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
-	@echo
-	@echo "Build finished; now you can run HTML Help Workshop with the" \
-	      ".hhp project file in $(BUILDDIR)/htmlhelp."
-
-qthelp: $(FLAGS)
-	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
-	@echo
-	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
-	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
-	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/kwant.qhcp"
-	@echo "To view the help file:"
-	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/kwant.qhc"
-
-latex:  $(GENERATEDPDF) $(FLAGS)
-	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
-	@echo
-	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
-	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
-	      "run these through (pdf)latex."
-
-changes:
-	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
-	@echo
-	@echo "The overview file is in $(BUILDDIR)/changes."
-
-linkcheck:
-	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
-	@echo
-	@echo "Link check complete; look for any errors in the above output " \
-	      "or in $(BUILDDIR)/linkcheck/output.txt."
-
-doctest:
-	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
-	@echo "Testing of doctests in the sources finished, look at the " \
-	      "results in $(BUILDDIR)/doctest/output.txt."
-
-%.pdf: %.svg
-	rsvg-convert -f pdf -o $@ $<
-
-# Make the image generation scripts by patching tutorial scipts.
-.SECONDARY:
-%.py: %.py.diff
-	@grep -v '^#HIDDEN' source/tutorial/$(notdir $@) >$@
-	@patch $@ $<
+clean:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# The image generation scripts depend on their unpatched originals
-define makedep
-source/images/$(1): source/tutorial/$(1)
-endef
-$(foreach name,$(SCRIPTS),$(eval $(call makedep,$(name))))
+latex:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-# Generation of images
-.%_flag: %.py
-	cd $(dir $<) && python3 $(notdir $<)
-	@touch $@
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/kwantdoctheme/static/kwantdoctheme.css

-/* This theme is based on pydoctheme by Georg Brandl. */
-
-@import url("default.css");
-
-body {
-    background-color: white;
-    margin-left: 1em;
-    margin-right: 1em;
-}
-
-/* Disable typewriter font in headings. */
-h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt {
-    font-family: "Bitstream Vera Sans", Verdana, sans-serif;
-    font-size: 100%;
-}
-
-div.body p, div.body dd, div.body li {
-    -webkit-hyphens: auto;
-    -moz-hyphens: auto;
-    -ms-hyphens: auto;
-    -o-hyphens: auto;
-    hyphens: auto;
-}
-
-div.related {
-    margin-bottom: 1.2em;
-    padding: 0.5em 0;
-    border-top: 1px solid #ccc;
-    margin-top: 0.5em;
-}
-
-dt:target, .highlighted {
-    background-color: #fbf1aa;
-}
-
-div.related:first-child {
-    border-top: 0;
-    border-bottom: 1px solid #ccc;
-}
-
-div.sphinxsidebar {
-    background-color: #eeeeee;
-    border-radius: 5px;
-    line-height: 130%;
-    font-size: smaller;
-    overflow: hidden;
-}
-
-div.sphinxsidebar h3, div.sphinxsidebar h4 {
-    margin-top: 1.5em;
-}
-
-div.sphinxsidebarwrapper > h3:first-child {
-    margin-top: 0.2em;
-}
-
-div.sphinxsidebarwrapper > ul > li > ul > li {
-    margin-bottom: 0.4em;
-}
-
-div.sphinxsidebar input {
-    font-family: 'Bitstream Vera Serif',  Georgia, serif
-    border: 1px solid #999999;
-    font-size: smaller;
-    border-radius: 3px;
-}
-
-div.sphinxsidebar input[type=text] {
-    max-width: 220px;
-}
-
-div.body {
-    padding: 0 0 0 1.2em;
-}
-
-div.body p {
-    line-height: 140%;
-}
-
-div.body h1, div.body h2, div.body h3, div.body h4, div.body h5, div.body h6 {
-    margin: 0;
-    border: 0;
-    padding: 0.3em 0;
-}
-
-div.body hr {
-    border: 0;
-    background-color: #ccc;
-    height: 1px;
-}
-
-div.body pre {
-    border-radius: 3px;
-    border: 1px solid #ac9;
-}
-
-div.body div.admonition, div.body div.impl-detail {
-    border-radius: 3px;
-}
-
-div.body div.impl-detail > p {
-    margin: 0;
-}
-
-div.body div.seealso {
-    border: 1px solid #dddd66;
-}
-
-tt, pre {
-    font-family: monospace, sans-serif;
-    font-size: 96.5%;
-    -webkit-hyphens: none;
-    -moz-hyphens: none;
-    -ms-hyphens: none;
-    -o-hyphens: none;
-    hyphens: none;
-}
-
-div.body tt {
-    border-radius: 3px;
-}
-
-div.body tt.descname {
-    font-size: 120%;
-}
-
-div.body tt.xref, div.body a tt {
-    font-weight: normal;
-}
-
-p.deprecated {
-    border-radius: 3px;
-}
-
-table.docutils {
-    border: 1px solid #ddd;
-    min-width: 20%;
-    border-radius: 3px;
-    margin-top: 10px;
-    margin-bottom: 10px;
-}
-
-table.docutils td, table.docutils th {
-    border: 1px solid #ddd !important;
-    border-radius: 3px;
-}
-
-table p, table li {
-    text-align: left !important;
-}
-
-table.docutils th {
-    background-color: #eee;
-    padding: 0.3em 0.5em;
-}
-
-table.docutils td {
-    background-color: white;
-    padding: 0.3em 0.5em;
-}
-
-table.footnote, table.footnote td {
-    border: 0 !important;
-}
-
-div.footer {
-    line-height: 150%;
-    margin-top: -2em;
-    text-align: right;
-    width: auto;
-    margin-right: 10px;
-}
-
-/* have arguments of functions or classes also a monospace font */
-table.longtable.docutils > tbody > tr > td:first-child,
-dl.function > dt,
-dl.class > dt,
-dl.method > dt
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 96.5%;
-}
-
-/* rescale font for <tt> so that it is again 96.5% with respect to body */
-table.longtable.docutils > tbody > tr > td:first-child tt,
-dl.function > dt tt,
-dl.class > dt tt,
-dl.method > dt tt
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 100%;
-}
-
-td.field-body strong
-{
-    font-family: "Bitstream Vera Sans Mono", monospace, serif;
-    font-size: 96.5%;
-}

doc/kwantdoctheme/theme.conf

-# This theme is based on pydoctheme by Georg Brandl
-
-[theme]
-inherit = default
-stylesheet = kwantdoctheme.css
-pygments_style = sphinx
-
-[options]
-bodyfont = "Bitstream Vera Serif", Georgia, serif
-headfont = "Bitstream Vera Sans", Verdana, sans-serif
-footerbgcolor = white
-footertextcolor = #555555
-relbarbgcolor = white
-relbartextcolor = #666666
-relbarlinkcolor = #444444
-sidebarbgcolor = white
-sidebartextcolor = #444444
-sidebarlinkcolor = #444444
-sidebarwidth = 300
-bgcolor = white
-textcolor = black
-linkcolor = #045e94
-visitedlinkcolor = #045e94
-headtextcolor = black
-headbgcolor = white
-headlinkcolor = #aaaaaa

doc/source/_static/kwant.css

-@import "kwantdoctheme.css";
-
-/* spacing around blockquoted fields in parameters/attributes/returns */
-/* Essential. Otherwise there is way too much space around*/
-td.field-body > blockquote {
-    margin-top: 0.1em;
-    margin-bottom: 0.5em;
-}
-
-.field-list th {
-  /* color: rgb(0,50,150); */
-  /* background-color: #EEE8AA; */
-  white-space: nowrap; /* Essential. Otherwise the colons can break
-                          into a new line */
-}
-
-table.field-list {
-  border-collapse: separate; /* Essential. Otherwise Parameters and Returns
-                                are sharing one solid colored field. That looks
-                                weird. */
-  border-spacing: 10px;
-  border-style: hidden;
-}
-
-div.specialnote-title {
-    font-size: 105%;
-    font-weight: bold;
-    font-color: #3B4D3C;
-    background-color: #DCE4DC;
-    padding: 1em;
-    padding-top: 0.4em;
-    padding-bottom: 0.4em;
-    margin-top: 10px;
-    margin-bottom: 10px;
-    border-width: 1px;
-    border-color: #546C55;
-    border-style: solid;
-}
-
-div.specialnote-body {
-    background-color: #DCE4DC;
-    padding: 1em;
-    padding-top: 0.1em;
-    padding-bottom: 0.4em;
-    margin-top: -10px;
-    margin-bottom: 10px;
-    border-width: 1px;
-    border-top-width: 0px;
-    border-color: #546C55;
-    border-style: solid;
-}

doc/source/_static/mathconf.js

+MathJax.Hub.Config({
+    TeX: {
+        Macros: {
+            bra: ['{\\left\\langle #1\\right|}',1],
+            ket: ['{\\left| #1\\right\\rangle}',1],
+            braket: ['\\left\\langle#1|#2\\right\\rangle', 2],
+            ri: '\\text{i}',
+            rd: '\\text{d}'
+        }
+    }
+});

doc/source/conf.py

@@ -11,12 +11,23 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
-import sys, os
-
+import sys
+import os
+import string
 from distutils.util import get_platform
-sys.path.insert(0, "../../build/lib.{0}-{1}.{2}".format(
-        get_platform(), *sys.version_info[:2]))
+
+package_path = os.path.abspath(
+    "../../build/lib.{0}-{1}.{2}"
+    .format(get_platform(), *sys.version_info[:2]))
+
+# Insert into sys.path so that we can import kwant here
+sys.path.insert(0, package_path)
+# Insert into PYTHONPATH so that jupyter-sphinx will pick it up
+os.environ['PYTHONPATH'] = ':'.join((package_path, os.environ.get('PYTHONPATH','')))
+
 import kwant
+import kwant.qsymm
+import kwant.continuum  # sphinx gets confused with lazy loading
 
 # -- General configuration -----------------------------------------------------
 
@@ -26,8 +37,9 @@ import kwant
 sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.autosummary',
-              'sphinx.ext.todo', 'sphinx.ext.pngmath', 'numpydoc',
-              'kwantdoc']
+              'sphinx.ext.todo', 'sphinx.ext.mathjax', 'sphinx.ext.napoleon',
+              'sphinx.ext.linkcode', 'jupyter_sphinx', 'sphinx_togglebutton',
+              'sphinxcontrib.rsvgconverter']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../templates']
@@ -43,7 +55,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = 'Kwant'
-copyright = '2011-2015, C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov, X. Waintal (CEA), and others'
+copyright = '2011-2017, C. W. Groth (CEA), M. Wimmer, A. R. Akhmerov, X. Waintal (CEA), and others'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -95,22 +107,20 @@ pygments_style = 'sphinx'
 # Do not show all class members automatically in the class documentation
 numpydoc_show_class_members = False
 
-# -- Options for HTML output ---------------------------------------------------
+# Jupyter Sphinx config
 
-# http://stackoverflow.com/questions/9728292/creating-latex-math-macros-within-sphinx
-pngmath_latex_preamble = r"""\newcommand{\bra}[1]{\left\langle#1\right|}
-\newcommand{\ket}[1]{\left|#1\right>}
-\newcommand{\braket}[2]{\left\langle#1|#2\right\rangle}
-\newcommand{\ri}{\text{i}}
-\newcommand{\rd}{\text{d}}
-"""
+jupyter_sphinx_thebelab_config = {
+    "binderOptions": {
+        "repo": "kwant-project/binder",
+        "ref": "master",
+    }
+}
+
+# -- Options for HTML output ---------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  Major themes that come with
 # Sphinx are currently 'default' and 'sphinxdoc'.
-html_theme = 'kwantdoctheme'
-html_theme_path = ['..']
-html_theme_options = {'collapsiblesidebar': True}
-html_style = 'kwant.css'
+html_theme = 'sphinx_book_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
@@ -129,7 +139,7 @@ html_style = 'kwant.css'
 
 # The name of an image file (relative to this directory) to place at the top
 # of the sidebar.
-#html_logo = None
+html_logo = "_static/kwant_logo.png"
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -179,13 +189,9 @@ html_domain_indices = False
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
-# Output file base name for HTML help builder.
-htmlhelp_basename = 'kwantdoc'
-
 
 # -- Options for LaTeX output --------------------------------------------------
 
-# http://thread.gmane.org/gmane.comp.python.sphinx.devel/4220/focus=4238
 latex_elements = {'papersize': 'a4paper',
                   'release': '',
                   'releasename': '',
@@ -201,7 +207,15 @@ r"""\makeatletter
     \renewcommand{\footrulewidth}{0.4pt}
   }
 \makeatother
-""" + pngmath_latex_preamble}
+
+\newcommand{\bra}[1]{\left\langle#1\right|}
+\newcommand{\ket}[1]{\left|#1\right>}
+\newcommand{\braket}[2]{\left\langle#1|#2\right\rangle}
+\newcommand{\ri}{\text{i}}
+\newcommand{\rd}{\text{d}}
+
+\usepackage{unicode-math}
+"""}
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
@@ -212,6 +226,10 @@ latex_documents = [
    'manual'),
 ]
 
+latex_engine = 'xelatex'
+
+latex_use_xindy = False  # Xindy not installable in CI environment
+
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
@@ -223,9 +241,6 @@ latex_documents = [
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
-# If false, no module index is generated.
-latex_use_modindex = False
-
 # This is needed too.
 latex_domain_indices = False
 
@@ -234,7 +249,9 @@ latex_domain_indices = False
 autosummary_generate = True
 
 autoclass_content = "both"
-autodoc_default_flags = ['show-inheritance']
+autodoc_default_options = {
+    'show-inheritance': True,
+}
 
 # -- Teach Sphinx to document bound methods like functions ---------------------
 import types
@@ -247,7 +264,7 @@ class BoundMethodDocumenter(autodoc.FunctionDocumenter):
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):
         # Return True iff `member` is a bound method.  Taken from
-        # <http://stackoverflow.com/a/1260881>.
+        # <https://stackoverflow.com/a/1260881>.
         return (isinstance(member, types.MethodType) and
                 member.__self__ is not None and
                 not issubclass(member.__self__.__class__, type) and
@@ -262,3 +279,56 @@ class BoundMethodDocumenter(autodoc.FunctionDocumenter):
 
 def setup(app):
     app.add_autodocumenter(BoundMethodDocumenter)
+
+
+# By default linkcheck only tries once, but experience has shown us that this test is
+# very non-specific for detecting dead links. Trying a few times should significantly
+# lower the probability of false positives.
+linkcheck_retries = 5
+# Some websites (particularly IoP) take a long time to respond. The combination of
+# this timeout and the retries should make this check sufficiently specific.
+linkcheck_timeout = 10
+
+nitpick_ignore = [('py:class', 'Warning'), ('py:class', 'Exception'),
+                  ('py:class', 'object'), ('py:class', 'tuple'),
+                  ('py:class', 'kwant.operator._LocalOperator'),
+                  ('py:class', 'numpy.ndarray'),
+                  ('py:class', 'kwant.solvers.common.BlockResult'),
+                  ('py:class', 'kwant.builder._FinalizedBuilderMixin')]
+
+
+# -- Make Sphinx insert source code links --------------------------------------
+def linkcode_resolve(domain, info):
+    def find_source():
+        # try to find the file and line number, based on code from numpy:
+        # https://github.com/numpy/numpy/blob/master/doc/source/conf.py#L286
+        obj = sys.modules[info['module']]
+        for part in info['fullname'].split('.'):
+            obj = getattr(obj, part)
+        import inspect
+        fn = inspect.getsourcefile(obj)
+        fn = os.path.relpath(fn, start=os.path.dirname(kwant.__file__))
+        source, lineno = inspect.getsourcelines(obj)
+        return fn, lineno, lineno + len(source) - 1
+
+    if domain != 'py' or not info['module']:
+        return None
+    try:
+        filename = 'kwant/%s#L%d-%d' % find_source()
+    except Exception:
+        filename = info['module'].replace('.', '/') + '.py'
+
+    # The following relies on the documented format of kwant.__version__.
+    rel = release.rstrip('.dirty')
+    if '.dev' in rel:
+        try:
+            refname = rel[rel.index('+g') + 2:]
+        except ValueError:
+            return
+    else:
+        refname = 'v' + rel
+
+    templ = os.environ.get(
+        "SOURCE_LINK_TEMPLATE",
+        "https://gitlab.kwant-project.org/kwant/kwant/blob/$r/$f")
+    return string.Template(templ).safe_substitute(r=refname, f=filename)