Adjust build instructions for conda-forge (#12)

- allow to depend on the xtb shared library
- include the xtb header also in this repository
- remove numpy from build dependencies
- move tests into the xtb directory
- change versioning to year based scheme
- fix packages to include whole source tree
- more detailed installation introduction

.travis.yml

@@ -27,7 +27,7 @@ install:
    - pip install -e .
 
 script:
-   - pytest -v --cov=xtb tests/
+   - pytest -v --cov=xtb --pyargs xtb
 
 after_success:
    - codecov

docs/ase-calculator.rst

@@ -1,3 +1,4 @@
+.. _ase:
 .. module:: xtb.ase
 
 Atomic Simulation Environment

docs/index.rst

@@ -5,8 +5,42 @@ This is the documentation of the Python API for the extended tight binding
 program (``xtb``).
 The project is hosted at `GitHub <https://github.com/grimme-lab/xtb-python>`_.
 
+
+.. code::
+
+   >>> from xtb.interface import Calculator
+   >>> from xtb.utils import get_method
+   >>> import numpy as np
+   >>> numbers = np.array([8, 1, 1])
+   >>> positions = np.array([
+   ... [ 0.00000000000000, 0.00000000000000,-0.73578586109551],
+   ... [ 1.44183152868459, 0.00000000000000, 0.36789293054775],
+   ... [-1.44183152868459, 0.00000000000000, 0.36789293054775]])
+   ...
+   >>> calc = Calculator(get_method("GFN2-xTB"), numbers, positions)
+   >>> res = calc.singlepoint()  # energy printed is only the electronic part
+      1     -5.1027888 -0.510279E+01  0.421E+00   14.83       0.0  T
+      2     -5.1040645 -0.127572E-02  0.242E+00   14.55       1.0  T
+      3     -5.1042978 -0.233350E-03  0.381E-01   14.33       1.0  T
+      4     -5.1043581 -0.602769E-04  0.885E-02   14.48       1.0  T
+      5     -5.1043609 -0.280751E-05  0.566E-02   14.43       1.0  T
+      6     -5.1043628 -0.188160E-05  0.131E-03   14.45      44.1  T
+      7     -5.1043628 -0.455326E-09  0.978E-04   14.45      59.1  T
+      8     -5.1043628 -0.572169E-09  0.192E-05   14.45    3009.1  T
+        SCC iter.                  ...        0 min,  0.022 sec
+        gradient                   ...        0 min,  0.000 sec
+   >>> res.get_energy()
+   -5.070451354836705
+   >>> res.get_gradient()
+   array([[ 6.24500451e-17 -3.47909735e-17 -5.07156941e-03]
+          [-1.24839222e-03  2.43536791e-17  2.53578470e-03]
+          [ 1.24839222e-03  1.04372944e-17  2.53578470e-03]])
+   >>> res.get_charges()
+   array([-0.56317912  0.28158956  0.28158956])
+
+
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 3
    :caption: Contents
 
    installation

docs/installation.rst

@@ -1,6 +1,29 @@
+.. _install:
+
 Installation
 ============
 
+For the basic functionalities the ``xtb-python`` project requires following
+packages:
+
+.. code::
+
+   cffi
+   numpy
+
+Additionally the project provides a calculator implementation for ASE (see :ref:`ase`) which becomes available if the ``ase`` package is installed.
+For integration with the QCArchive infrastructure (see :ref:`qcarchive`) the ``qcelemental`` package is required.
+
+Of course, the package depends on the `extended tight binding program package <https://xtb-docs.readthedocs.io>`_ as well, directly or indirectly.
+Depending on how ``xtb-python`` was packaged it requires an installation of ``xtb`` or it will be able to provide its own.
+For more details on the ``xtb`` API dependency see :ref:`building`.
+
+
+.. _building:
+
+Building from Source
+--------------------
+
 To install ``xtb-python`` from source clone the repository from GitHub with
 
 .. code::
@@ -10,9 +33,12 @@ To install ``xtb-python`` from source clone the repository from GitHub with
    git submodule update --init
 
 This will ensure that you have access to the ``xtb-python`` and the parent ``xtb`` repository, with the latter to be found in ``subprojects/xtb``.
-It is highly recommend to make yourself familiar with building ``xtb`` first.
 
-To work with ``xtb-python`` it is necessary to build the extension to the ``xtb`` API first, this is accomplised by using meson and the C foreign function interface.
+
+Building the Extension Module
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To work with ``xtb-python`` it is necessary to build the extension to the ``xtb`` API first, this is accomplised by using meson and the C foreign function interface (CFFI).
 Following modules should be available to build this project:
 
 .. code::
@@ -21,8 +47,6 @@ Following modules should be available to build this project:
    numpy
    meson  # build only
 
-Additionally you will need a development version of Python, for the Python headers, a Fortran and a C compiler (GCC 7 or newer or Intel 17 or newer) and a linear algebra backend (providing LAPACK and BLAS API).
-
 To install the meson build system first check your package manager for an up-to-date meson version, usually this will also install ninja as dependency.
 Alternatively, you can install the latest version of meson and ninja with ``pip`` (or ``pip3`` depending on your system):
 
@@ -42,14 +66,51 @@ Now, setup the project by building the CFFI extension module from the ``xtb`` AP
 
 .. code::
 
-   meson setup build --prefix=$PWD --libdir=xtb
+   meson setup build --prefix=$PWD --libdir=xtb --default-library=shared
    ninja -C build install
 
+This step will create the CFFI extension ``_libxtb`` and place it in the ``xtb`` directory.
+
+
+Meson cannot find xtb dependency
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If meson cannot find your ``xtb`` installation check if you have ``pkg-config`` installed and that ``xtb`` can be found using
+
+.. code::
+
+   pkg-config xtb --print-errors
+
+In case this fails ensure that the ``xtb.pc`` file is in a directory in the ``PKG_CONFIG_PATH`` and retry.
+For the official release tarball you possible have to edit the first line of ``xtb.pc`` to point to the location where you installed ``xtb``:
+
+.. code:: diff
+
+   --- a/lib/pkgconfig/xtb.pc
+   +++ b/lib/pkgconfig/xtb.pc
+   @@ -1,4 +1,4 @@
+   -prefix=/
+   +prefix=/absolute/path/to/xtb
+    libdir=${prefix}/lib
+    includedir=${prefix}/include/xtb
+
+.. note::
+
+   Installs from conda-forge should work out-of-box.
+
+
+Dealing with Several Versions of Python
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 If you have several versions of Python installed you can point meson with the ``-Dpy=<version>`` option to the correct one.
 Depending on your setup you have to export your compilers (``CC`` and ``FC``) first and set the ``-Dla_backend=<name>`` and ``-Dopenmp=<bool>`` option accordingly.
-For more information on the build with meson, follow the guide in the ``xtb`` repository `here <https://github.com/grimme-lab/xtb/blob/master/meson/README.adoc>`_.
 
-This step will create the CFFI extension ``_libxtb`` and place it in the ``xtb`` directory.
+
+.. _devel-install:
+
+Installing in Development Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 After creating the ``_libxtb`` extension, the Python module can be installed as usual with
 
 .. code::
@@ -62,3 +123,66 @@ You can test your setup by opening a new Python interpreter and try to import th
 .. code::
 
    >>> import xtb.interface
+
+If you also want to use extensions install with
+
+.. code::
+
+   pip install -e '.[ase,qcschema]'
+
+Now you can test your installation with
+
+.. code::
+
+   pytest --pyargs xtb
+
+
+Helpful Tools
+^^^^^^^^^^^^^
+
+We aim for a high quality code base and encourage substainable development models.
+
+Please, install a linter like ``flake8`` or ``pylint`` to catch errors before they become bugs.
+Also, typehints are mandatory in this project, you should typecheck locally with ``mypy``.
+A consistent coding style is enforced by using ``black``, every source file should be reformatted using ``black``, the only exceptions are tests.
+
+
+Building without Upstream Dependency
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+For convenience we also offer a mode to work without an upstream ``xtb`` dependency, this can be quite handy if you also want to work on the ``xtb`` API itself or want to create a failsafe package that cannot break due to ABI or API incompatibilities.
+
+.. note::
+
+   It is highly recommend to make yourself familiar with building ``xtb`` first.
+
+For this approach we follow the same scheme as with the normal extension build.
+You will need the following packages installed
+
+.. code::
+
+   cffi
+   numpy
+   meson  # build only
+
+Additionally you will need a development version of Python, for the Python headers, a Fortran and a C compiler (GCC 7 or newer or Intel 17 or newer) and a linear algebra backend (providing LAPACK and BLAS API).
+
+We closely follow the approach from before, but we change the configuration of the extension build to
+
+.. code::
+
+   meson setup build --prefix=$PWD --libdir=xtb --default-library=static
+   ninja -C build install
+
+
+Depending on how you acquired the project mesons wrap-tool will first need to download the ``xtb`` source code.
+Instead of dynamically depending on ``xtb`` the complete project will be build and included as a whole into the CFFI extension module, making your ``xtb-python`` effectively independent of ``xtb``.
+
+You can pass the ``-Dopenmp=<bool>`` and ``-Dla_backend=<netlib|openblas|mkl>`` in the configuration step to configure the ``xtb`` build.
+To change the compiler used export them in the environment variables ``CC`` and ``FC``.
+
+.. tip::
+
+   For more information on the build with meson, follow the guide in the ``xtb`` repository `here <https://github.com/grimme-lab/xtb/blob/master/meson/README.adoc>`_.
+
+From here you can proceed with :ref:`devel-install`.