feat: create guidelines for an issue and getting help (#528)

* Add a GitHub issue template and a convenience function to display the status and
version of important dependencies. (You can see a very similar setup when you go to https://github.com/pandas-dev/pandas/issues/new.)
* Add a link to a guide on how to ask a good question.
* Add function to get version information

.github/ISSUE_TEMPLATE.md

@@ -0,0 +1,28 @@
+#### Problem description
+
+Please explain:
+* **what** you tried to achieve,
+* **how** you went about it (referring to the code sample), and
+* **why** the current behaviour is a problem and what output
+  you expected instead.
+
+#### Code Sample
+
+Create a [minimal, complete, verifiable example
+](https://stackoverflow.com/help/mcve).
+
+```python
+# Paste your code here.
+
+```
+
+#### Actual Output
+
+#### Expected Output
+
+#### Output of `cobra.show_versions()`
+
+<details>
+# Paste the output of `import cobra;cobra.show_versions()` here.
+
+</details>

README.rst

@@ -18,7 +18,7 @@ for:
 
 - creating and managing metabolic models
 - accessing popular solvers
-- analyzing models with methods such as FVA, FBA, pFBA, MOMA etc. 
+- analyzing models with methods such as FVA, FBA, pFBA, MOMA etc.
 - inspecting models and drawing conclusions on gene essentiality,
   testing consequences of knock-outs etc.
 
@@ -36,10 +36,12 @@ also be
 `downloaded <https://readthedocs.org/projects/cobrapy/downloads/>`_.
 
 Please use the `Google
-Group <http://groups.google.com/group/cobra-pie>`_ for help.
-Alternatively, you can use
-`gitter.im <https://gitter.im/opencobra/cobrapy>`_ for quick questions
-and discussions about cobrapy (faster response times).
+Group <http://groups.google.com/group/cobra-pie>`_ for help. By writing a well formulated question, with sufficient
+detail, you are much more likely to quickly receive a good answer! Please refer to these `StackOverflow
+guidelines <https://stackoverflow.com/help/how-to-ask>`_ on how to ask questions.
+Alternatively, you can use `gitter.im <https://gitter.im/opencobra/cobrapy>`_ for quick questions
+and discussions about cobrapy (faster response times). Please keep in mind that answers are provided on a volunteer
+basis.
 
 More information about opencobra is available at the
 `website <http://opencobra.github.io/>`_.
@@ -68,7 +70,7 @@ Contributing
 ~~~~~~~~~~~~
 
 Contributions are always welcome! Please read the `contributions
-guideline <CONTRIBUTING.rst>`_ to get started.
+guideline <.github/CONTRIBUTING.rst>`_ to get started.
 
 License
 -------
@@ -100,5 +102,5 @@ Public License for more details.
 .. |Gitter| image:: https://badges.gitter.im/opencobra/cobrapy.svg
    :target: https://gitter.im/opencobra/cobrapy?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
 .. |Waffle| image:: https://badge.waffle.io/opencobra/cobrapy.png?label=ready&title=Ready
-   :target: https://waffle.io/opencobra/cobrapy 
+   :target: https://waffle.io/opencobra/cobrapy
    :alt: 'Stories in Ready'

cobra/__init__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 
-from __future__ import absolute_import, print_function
+from __future__ import absolute_import
 
 # set the warning format to be on a single line
 import warnings as _warnings
@@ -11,6 +11,7 @@
 from cobra import design, flux_analysis, io
 from cobra.core import (
     DictList, Gene, Metabolite, Model, Object, Reaction, Species)
+from cobra.util.version_info import show_versions
 
 __version__ = "0.6.2"
 

cobra/test/test_util.py

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 from __future__ import absolute_import
 
+from builtins import zip
+
 import re
 from copy import copy, deepcopy
 from pickle import HIGHEST_PROTOCOL, dumps, loads
@@ -9,6 +11,8 @@
 from six.moves import range
 
 from cobra import DictList, Object
+from cobra.util.version_info import (
+    get_sys_info, get_pkg_info, show_versions, SYS_ORDER, PKG_ORDER)
 
 
 @pytest.fixture(scope="function")
@@ -293,3 +297,58 @@ def test_union(self, dict_list):
         # should only add 1 element
         assert len(test_list) == 2
         assert test_list.index("test2") == 1
+
+
+class TestVersionInfo:
+    SKIP_OPTIONAL = frozenset([
+        "cobra", "python-libsbml", "lxml", "matplotlib", "palettable", "scipy",
+        "pymatbridge"])
+
+    @pytest.fixture(scope="module")
+    def sys_info(self):
+        return get_sys_info()
+
+    @pytest.fixture(scope="module")
+    def pkg_info(self):
+        return get_pkg_info()
+
+    @pytest.mark.parametrize("key", SYS_ORDER)
+    def test_sys_info_key(self, key, sys_info):
+        assert key in sys_info
+
+    @pytest.mark.parametrize("key", SYS_ORDER)
+    def test_sys_info_value(self, key, sys_info):
+        assert len(sys_info[key]) > 0
+
+    @pytest.mark.parametrize("key", PKG_ORDER)
+    def test_pkg_info_key(self, key, pkg_info):
+        if key in self.SKIP_OPTIONAL:
+            pytest.skip()
+        assert key in pkg_info
+
+    @pytest.mark.parametrize("key", PKG_ORDER)
+    def test_pkg_info_value(self, key, pkg_info):
+        if key in self.SKIP_OPTIONAL:
+            pytest.skip()
+        assert len(pkg_info[key]) > 0
+
+    def test_show_versions(self, sys_info, pkg_info, capsys):
+        show_versions()
+        out, err = capsys.readouterr()
+        lines = out.split("\n")
+        i = 3
+        for key in SYS_ORDER:
+            line = lines[i]
+            assert line.startswith(key)
+            assert line.endswith(sys_info[key])
+            i += 1
+        i += 3
+        for key in PKG_ORDER:
+            line = lines[i]
+            if key in self.SKIP_OPTIONAL:
+                if line.startswith(key):
+                    i += 1
+                continue
+            assert line.startswith(key)
+            assert line.endswith(pkg_info[key])
+            i += 1

cobra/util/version_info.py

@@ -0,0 +1,79 @@
+# -*- coding: utf-8 -*-
+
+# Adapated from:
+# https://github.com/pandas-dev/pandas/blob/master/pandas/util/_print_versions.py
+# which is published under a BSD license.
+
+from __future__ import absolute_import, print_function
+
+from builtins import dict
+
+import platform
+
+import pip
+
+__all__ = ("show_versions",)
+
+SYS_ORDER = [
+    "OS",
+    "OS-release",
+    "Python"
+]
+PKG_ORDER = [
+    "pip",
+    "setuptools",
+    "cobra",
+    "future",
+    "swiglpk",
+    "optlang",
+    "ruamel.yaml",
+    "pandas",
+    "numpy",
+    "tabulate",
+    "python-libsbml",
+    "lxml",
+    "scipy",
+    "matplotlib",
+    "palettable",
+    "pymatbridge"
+]
+
+
+def get_sys_info():
+    """Returns system information as a dict."""
+    blob = dict()
+    blob["OS"] = platform.system()
+    blob["OS-release"] = platform.release()
+    blob["Python"] = platform.python_version()
+    return blob
+
+
+def get_pkg_info():
+    """Returns Python package information as a dict."""
+    # TODO: Basically copying the requirements from setup.py is brittle,
+    # should come up with a better way in future, for example,
+    # using requirements files that can be read in.
+    dependencies = frozenset(PKG_ORDER)
+    blob = dict()
+    for dist in pip.get_installed_distributions():
+        if dist.project_name in dependencies:
+            blob[dist.project_name] = dist.version
+    return blob
+
+
+def show_versions():
+    """Print the formatted information to standard out."""
+    info = get_sys_info()
+    info.update(get_pkg_info())
+    format_str = "{:<%d} {:>%d}" % (max(map(len, info)),
+                                    max(map(len, info.values())))
+    print("\nSystem Information")
+    print("==================")
+    for name in SYS_ORDER:
+        print(format_str.format(name, info[name]))
+
+    print("\nPackage Versions")
+    print("================")
+    for name in PKG_ORDER:
+        if name in info:
+            print(format_str.format(name, info[name]))