feat(cli): add cli to honeybee

This commit adds a minimal but extendable command line interface to honeybee.

I'm using click to create the `cli` which gives us a great level of flexibility and fits our needs for ladybug tools.

Since the command line interface might not be needed for all the installations I added click to setup.py as an `extra_requires` for `cli`. One needs to use `pip install honeybee-core[cli]` or `pip install honeybee-core[all]` to install both honeybee core and the cli dependencies.

README.md

@@ -1,4 +1,4 @@
-![Honeybee](http://www.ladybug.tools/assets/img/honeybee.png)
+![Honeybee](https://www.ladybug.tools/assets/img/honeybee.png)
 
 [![Build Status](https://travis-ci.org/ladybug-tools/honeybee-core.svg?branch=master)](https://travis-ci.org/ladybug-tools/honeybee-core)
 [![Coverage Status](https://coveralls.io/repos/github/ladybug-tools/honeybee-core/badge.svg?branch=master)](https://coveralls.io/github/ladybug-tools/honeybee-core)
@@ -7,24 +7,33 @@
 
 # honeybee-core
 
-Honeybee core library.
+Honeybee is a collection of Python libraries to create, run and visualize
+daylight ([RADIANCE](https://radiance-online.org//)) and energy
+([EnergyPlus](https://energyplus.net/)/[OpenStudio](https://www.openstudio.net/)) models.
 
-# NOTE
+This repository is the core repository that provides honeybee's common functionalities.
+To extend these functionalities you should install available Honeybee extensions or write
+your own.
 
-This repository will be renamed to `honeybee` once the current `honeybee` repository is
-renamed to `honeybee-radiance`.
+Here are a number of frequently used extensions for Honeybee:
 
-## What is this repository?
+- [honeybee-energy](https://github.com/ladybug-tools/honeybee-energy): Adds Energy simulation to Honeybee.
+- [honeybee-radiance](https://github.com/ladybug-tools/honeybee-radiance): Adds daylight simulation to Honeybee.
 
-Honeybee is a collection of Python library to create, run and visualize the results of
-daylight ([RADIANCE](https://radiance-online.org//)) and energy analysis
-([EnergyPlus](https://energyplus.net/)/[OpenStudio](https://www.openstudio.net/)).
 
-This repository is the main repository for Honeybee core libraries. To extend the
-functionalities of this library you should install available Honeybee extensions or write
-your own. See [here](https://github.com/ladybug-tools/honeybee-extension) to get started
-with writing your first extension.
+# Installation
 
-Here are a number of available extensions for Honeybee:
+To install the core library try:
 
-- [honeybee-energy](https://github.com/ladybug-tools/honeybee-energy): Adds Energy simulation to Honeybee.
+`pip install -U honeybee-core`
+
+If you want to also include the command line interface try:
+
+`pip install -U honeybee-core[cli]`
+
+To check if Honeybee command line is installed correctly try `honeybee viz` and you
+should get a `viiiiiiiiiiiiizzzzzzzzz!` back in response! :bee:
+
+# Documentation
+
+[API documentation](https://www.ladybug.tools/honeybee-core/docs/)

dev-requirements.txt

@@ -6,4 +6,5 @@ Sphinx==1.8.5
 sphinx-bootstrap-theme==0.6.5
 sphinxcontrib-fulltoc==1.2.0
 sphinxcontrib-websupport==1.1.0
+sphinx-click==2.2.0
 twine==1.13.0

docs/cli.rst

@@ -0,0 +1,6 @@
+honeybee command line interface
+===============================
+
+.. click:: honeybee.cli:main
+   :prog: honeybee
+   :show-nested:

docs/conf.py

@@ -14,7 +14,7 @@
 #
 import os
 import sys
-sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
@@ -46,8 +46,9 @@
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
     'sphinx.ext.githubpages',
-	'sphinxcontrib.fulltoc',
-	'sphinx.ext.napoleon'
+    'sphinxcontrib.fulltoc',
+    'sphinx.ext.napoleon',
+    'sphinx_click.ext'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/index.rst

@@ -1,16 +1,44 @@
-.. Honeybee documentation master file, created by
-   sphinx-quickstart on Wed Mar 13 20:09:41 2019.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
 
 Welcome to Honeybee's documentation!
-===================================
+=========================================
+
+.. image:: http://www.ladybug.tools/assets/img/honeybee.png
+
+Honeybee is a collection of Python libraries to create, run and visualize the results of
+daylight `RADIANCE <https://radiance-online.org/>`_ and energy analysis
+`EnergyPlus <https://energyplus.net/>`_ / `OpenStudio <https://www.openstudio.net/>`_.
+
+Installation
+============
+
+To install the core library try ``pip install -U honeybee-core``.
+
+If you want to also include the command line interface try ``pip install -U honeybee-core[cli]``.
+
+To check if the Honeybee command line is installed correctly try ``honeybee viz`` and you
+should get a ``viiiiiiiiiiiiizzzzzzzzz!`` back in response!
+
+
+Documentation
+=============
+
+This document includes `Honeybee API documentation <#honeybee>`_ and 
+`Honeybee Command Line Interface <#id1>`_ documentation for ``honeybee core`` and does
+not include the documentation for honeybee extensions. For each extension refer to
+extension's documentation page.
+
+Here are a number of Honeybee popular extensions:
+
+- `honeybee-energy <https://ladybug.tools/honeybee-energy/docs>`_
+- `honeybee-radiance <https://ladybug.tools/honeybee-radiance/docs>`_
+
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
 .. include:: modules.rst
+.. include:: cli.rst
 
 
 Indices and tables

honeybee/__init__.py

@@ -2,19 +2,18 @@
 import sys
 import importlib
 import pkgutil
-
+import logging
 
 #  find and import honeybee extensions
 #  this is a critical step to add additional functionalities to honeybee core library.
-extensions = {
-    name: importlib.import_module(name)
-    for finder, name, ispkg
-    in pkgutil.iter_modules()
-    if name.startswith('honeybee_')
-}
-
-for key in extensions:
-    print('Successfully imported: {}'.format(key))
-
-# This is a variable to check if the library is a [+] library.
-setattr(sys.modules[__name__], 'isplus', False)
+extensions = {}
+for finder, name, ispkg in pkgutil.iter_modules():
+    if not name.startswith('honeybee_'):
+        continue
+    try:
+        extensions[name] = importlib.import_module(name)
+    except Exception:
+        print(
+            'Failed to import {0}!'
+            ' To see full error message try `import {0}`'.format(name)
+        )

honeybee/__main__.py

@@ -0,0 +1,4 @@
+from honeybee.cli import main
+
+if __name__ == '__main__':
+    main()

honeybee/cli.py

@@ -0,0 +1,78 @@
+"""
+Command Line Interface (CLI) entry point for honeybee and honeybee extensions.
+
+Use this file only to add command related to honeybee-core. For adding extra commands
+from each extention see below.
+
+Honeybee is using click (https://click.palletsprojects.com/en/7.x/) for creating the CLI.
+You can extend the command line interface from inside each extention by following these
+steps:
+
+1. Create a ``cli.py`` file in your extension.
+2. Import the ``main`` function from this ``honeybee.cli``.
+3. Add your commands and command groups to main using add_command method.
+4. Add ``import [your-extention].cli`` to ``__init__.py`` file to the commands are added
+   to the cli when the module is loaded.
+
+The good practice is to group all your extention commands in a command group named after
+the extension. This will make the commands organized under extension namespace. For
+instance commands for `honeybee-radiance` will be called like ``honeybee radiance [radiance-command]``. 
+
+
+.. code-block:: python
+
+    import click
+    from honeybee.cli import main
+
+    @click.group()
+    def radiance():
+        pass
+
+    # add commands to radiance group
+    @radiance.command('daylight-factor')
+    # ...
+    def daylight_factor():
+        pass
+
+
+    # finally add the newly created commands to honeybee cli
+    main.add_command(radiance)
+
+    # do not forget to import this module in __init__.py otherwise it will not be added
+    # to honeybee commands.
+
+Note:
+
+    For extension with several commands you can use a folder structure instead of a single
+    file. Refer to ``honeybee-radiance`` for an example.
+
+"""
+
+try:
+    import click
+except ImportError:
+    raise ImportError(
+        'click module is not installed. Try `pip install honeybee-core[cli]` command.'
+    )
+import importlib
+import sys
+import logging
+import honeybee
+
+# use this logger for logging inside this file and all the extensions
+_logger = logging.getLogger(__name__)
+
+@click.group()
+@click.version_option()
+def main():
+    pass
+
+
+@main.command('viz')
+def viz():
+    """Check if honeybee is flying!"""
+    click.echo('viiiiiiiiiiiiizzzzzzzzz!')
+
+
+if __name__ == "__main__":
+    main()

setup.py

@@ -1,6 +1,5 @@
 import re
 import setuptools
-import sys
 
 with open("README.md", "r") as fh:
     long_description = fh.read()
@@ -10,16 +9,22 @@
 
 setuptools.setup(
     name="honeybee-core",
-    use_scm_version = True,
+    use_scm_version=True,
     setup_requires=['setuptools_scm'],
     author="Ladybug Tools",
     author_email="info@ladybug.tools",
-    description="Honeybee is a Python library to create, run and visualize the results of environmental simulation. See plugins (e.g. honeybee_radiance) for specific simulation type.",
+    description="Honeybee is a Python library to create, run and visualize the results of environmental simulation. See extensions (e.g. honeybee_radiance) for specific simulation type.",
     long_description=long_description,
     long_description_content_type="text/markdown",
     url="https://github.com/ladybug-tools/honeybee-core",
     packages=setuptools.find_packages(exclude=["tests"]),
     install_requires=requirements,
+    extra_requires={
+        'cli': ['click>=5.1']
+    },
+    entry_points={
+        "console_scripts": ["honeybee = honeybee.cli:main"]
+    },
     classifiers=[
         "Programming Language :: Python :: 2.7",
         "Programming Language :: Python :: 3.6",