Merge pull request #8 from TUW-GEO/readme_rtd

Update readme and pyscaffold version

.gitignore

@@ -10,6 +10,7 @@
 __pycache__/*
 .cache/*
 .*.swp
+*/.ipynb_checkpoints/*
 
 # Project files
 .ropeproject

CHANGES.rst

@@ -2,6 +2,12 @@
 Changelog
 =========
 
+Version v0.0.X
+==============
+
+- Update readme structure
+- Add read the docs
+
 Version v0.0.3
 ==============
 

README.rst

@@ -5,20 +5,19 @@ Equi7Grid
 .. image:: https://travis-ci.org/TUW-GEO/Equi7Grid.svg?branch=master
     :target: https://travis-ci.org/TUW-GEO/Equi7Grid
 
+.. image:: https://coveralls.io/repos/github/TUW-GEO/Equi7Grid/badge.svg?branch=master
+    :target: https://coveralls.io/github/TUW-GEO/Equi7Grid?branch=master
+
 .. image:: https://badge.fury.io/py/Equi7Grid.svg
     :target: https://badge.fury.io/py/Equi7Grid
 
+.. image:: https://readthedocs.org/projects/equi7grid/badge/?version=latest
+    :target: https://equi7grid.readthedocs.io/en/latest/?badge=latest
+
 A python class for working with Equi7Grid - how to convert to - how to use the tiling system - etc.
 
 It's a python package that handles the geometric and geographic operations of a gridded and tiled projection system.
-It was designed for data cubes ingesting satellite imagery and builds the basis for the Equi7Grid (see https://github
-.com/TUW-GEO/Equi7Grid).
-
-
-Note
-====
-
-Installs for numba, scripy and gdal are required from conda or conda-forge.
+It was designed for data cubes ingesting satellite imagery and builds the basis for the Equi7Grid (see https://github.com/TUW-GEO/Equi7Grid).
 
 A detailed documentation on the Equi7Grid definition is at:
 
@@ -27,3 +26,90 @@ A detailed documentation on the Equi7Grid definition is at:
 Overlays for visualisation in Google Earth can be found here:
 
 ~/docs/doc_files/google_earth_overlays/
+
+Citation
+========
+
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.1048530.svg
+   :target: https://doi.org/10.5281/zenodo.1048530
+
+If you use the software in a publication then please cite it using the Zenodo DOI.
+Be aware that this badge links to the latest package version.
+
+Please select your specific version at https://doi.org/10.5281/zenodo.1048530 to get the DOI of that version.
+You should normally always use the DOI for the specific version of your record in citations.
+This is to ensure that other researchers can access the exact research artefact you used for reproducibility.
+
+You can find additional information regarding DOI versioning at http://help.zenodo.org/#versioning
+
+Installation
+============
+
+This package should be installable through pip:
+
+.. code::
+
+    pip install Equi7Grid
+
+Installs for numba, scripy and gdal are required from conda or conda-forge.
+
+Contribute
+==========
+
+We are happy if you want to contribute. Please raise an issue explaining what
+is missing or if you find a bug. We will also gladly accept pull requests
+against our master branch for new features or bug fixes.
+
+Development setup
+-----------------
+
+For Development we recommend a ``conda`` environment.
+
+Example installation script
+---------------------------
+
+The following script will install miniconda and setup the environment on a UNIX
+like system. Miniconda will be installed into ``$HOME/miniconda``.
+
+.. code::
+
+   wget https://repo.continuum.io/miniconda/Miniconda-latest-Linux-x86_64.sh -O miniconda.sh
+   bash miniconda.sh -b -p $HOME/miniconda
+   export PATH="$HOME/miniconda/bin:$PATH"
+   conda create -n equi7grid_env python=2.7 numpy scipy pip gdal pyproj numba
+   source activate equi7grid_env
+   pip install pytileproj
+
+
+This script adds ``$HOME/miniconda/bin`` temporarily to the ``PATH`` to do this
+permanently add ``export PATH="$HOME/miniconda/bin:$PATH"`` to your ``.bashrc``
+or ``.zshrc``
+
+The last line in the example activates the ``equi7grid_env`` environment.
+
+After that you should be able to run:
+
+.. code::
+
+    python setup.py test
+
+to run the test suite.
+
+Guidelines
+----------
+
+If you want to contribute please follow these steps:
+
+- Fork the Equi7Grid repository to your account
+- Clone the repository
+- make a new feature branch from the Equi7Grid master branch
+- Add your feature
+- Please include tests for your contributions in one of the test directories.
+  We use py.test so a simple function called test_my_feature is enough
+- submit a pull request to our master branch
+
+Note
+====
+
+This project has been set up using PyScaffold 2.5.11. For details and usage
+information on PyScaffold see http://pyscaffold.readthedocs.org/.

docs/conf.py

@@ -45,7 +45,7 @@
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo',
               'sphinx.ext.autosummary', 'sphinx.ext.viewcode', 'sphinx.ext.coverage',
-              'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.pngmath',
+              'sphinx.ext.doctest', 'sphinx.ext.ifconfig', 'sphinx.ext.mathjax',
               'sphinx.ext.napoleon']
 
 # Add any paths that contain templates here, relative to this directory.
@@ -62,7 +62,7 @@
 
 # General information about the project.
 project = u'Equi7Grid'
-copyright = u'2017, Bernhard Bauer-Marschallinger'
+copyright = u'2018, Bernhard Bauer-Marschallinger'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/index.rst

@@ -1,29 +1,4 @@
-=========
-Equi7Grid
-=========
-
-This is the documentation of **Equi7Grid**.
-
-.. note::
-
-    This is the main page of your project's `Sphinx <http://sphinx-doc.org/>`_
-    documentation. It is formatted in `reStructuredText
-    <http://sphinx-doc.org/rest.html>`__. Add additional pages by creating
-    rst-files in ``docs`` and adding them to the `toctree
-    <http://sphinx-doc.org/markup/toctree.html>`_ below. Use then
-    `references <http://sphinx-doc.org/markup/inline.html>`__ in order to link
-    them from this page, e.g. :ref:`authors <authors>` and :ref:`changes`.
-    It is also possible to refer to the documentation of other Python packages
-    with the `Python domain syntax
-    <http://sphinx-doc.org/domains.html#the-python-domain>`__. By default you
-    can reference the documentation of `Sphinx <http://sphinx.pocoo.org>`__,
-    `Python <http://docs.python.org/>`__, `matplotlib
-    <http://matplotlib.sourceforge.net>`__, `NumPy
-    <http://docs.scipy.org/doc/numpy>`__, `Scikit-Learn
-    <http://scikit-learn.org/stable>`__, `Pandas
-    <http://pandas.pydata.org/pandas-docs/stable>`__, `SciPy
-    <http://docs.scipy.org/doc/scipy/reference/>`__. You can add more by
-    extending the ``intersphinx_mapping`` in your Sphinx's ``conf.py``.
+.. include:: ../README.st
 
 Contents
 ========

equi7grid/__init__.py

@@ -1,3 +1,4 @@
+# -*- coding: utf-8 -*-
 import pkg_resources
 
 try:

setup.cfg

@@ -24,7 +24,8 @@ classifier =
 
 [files]
 # Add here 'data_files', 'packages' or 'namespace_packages'.
-# Additional data files are defined as key value pairs of source and target:
+# Additional data files are defined as key value pairs of target directory
+# and source location from the root of the repository:
 packages =
     equi7grid
 # data_files =

setup.py

@@ -3,7 +3,7 @@
 """
     Setup file for equi7grid.
 
-    This file was generated with PyScaffold 2.5.6, a tool that easily
+    This file was generated with PyScaffold 2.5.11, a tool that easily
     puts up a scaffold for your new Python project. Learn more under:
     http://pyscaffold.readthedocs.org/
 """

tests/conftest.py

@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+"""
+    Dummy conftest.py for equi7grid.
+
+    If you don't know what this is for, just leave it empty.
+    Read more about conftest.py under:
+    https://pytest.org/latest/plugins.html
+"""
+from __future__ import print_function, absolute_import, division
+
+import pytest