diff --git a/docs/Makefile b/docs/Makefile index e8b712ce8a1c8..69893c438471d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -57,7 +57,7 @@ html: .PHONY: livehtml livehtml: - sphinx-autobuild --port 0 -B -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + sphinx-autobuild -z ../homeassistant/ --port 0 -B -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html .PHONY: dirhtml dirhtml: diff --git a/docs/source/_ext/edit_on_github.py b/docs/source/_ext/edit_on_github.py new file mode 100644 index 0000000000000..cb6a45f058a83 --- /dev/null +++ b/docs/source/_ext/edit_on_github.py @@ -0,0 +1,47 @@ +""" +Sphinx extension to add ReadTheDocs-style "Edit on GitHub" links to the +sidebar. + +Loosely based on https://github.com/astropy/astropy/pull/347 +""" + +import os +import warnings + + +__licence__ = 'BSD (3 clause)' + + +def get_github_url(app, view, path): + return ( + 'https://github.com/{project}/{view}/{branch}/{src_path}{path}'.format( + project=app.config.edit_on_github_project, + view=view, + branch=app.config.edit_on_github_branch, + src_path=app.config.edit_on_github_src_path, + path=path)) + + +def html_page_context(app, pagename, templatename, context, doctree): + if templatename != 'page.html': + return + + if not app.config.edit_on_github_project: + warnings.warn("edit_on_github_project not specified") + return + if not doctree: + warnings.warn("doctree is None") + return + path = os.path.relpath(doctree.get('source'), app.builder.srcdir) + show_url = get_github_url(app, 'blob', path) + edit_url = get_github_url(app, 'edit', path) + + context['show_on_github_url'] = show_url + context['edit_on_github_url'] = edit_url + + +def setup(app): + app.add_config_value('edit_on_github_project', '', True) + app.add_config_value('edit_on_github_branch', 'master', True) + app.add_config_value('edit_on_github_src_path', '', True) # 'eg' "docs/" + app.connect('html-page-context', html_page_context) diff --git a/docs/source/_templates/links.html b/docs/source/_templates/links.html new file mode 100644 index 0000000000000..57a2e09f99e76 --- /dev/null +++ b/docs/source/_templates/links.html @@ -0,0 +1,8 @@ + +
diff --git a/docs/source/_templates/sourcelink.html b/docs/source/_templates/sourcelink.html new file mode 100644 index 0000000000000..8cf2c4f92ae78 --- /dev/null +++ b/docs/source/_templates/sourcelink.html @@ -0,0 +1,13 @@ +{%- if show_source and has_source and sourcename %} +

{{ _('This Page') }}

+ +{%- endif %} diff --git a/docs/source/api/bootstrap.rst b/docs/source/api/bootstrap.rst new file mode 100644 index 0000000000000..363f796996165 --- /dev/null +++ b/docs/source/api/bootstrap.rst @@ -0,0 +1,7 @@ +.. _bootstrap_module: + +:mod:`homeassistant.bootstrap` +------------------------- + +.. automodule:: homeassistant.bootstrap + :members: diff --git a/docs/source/api/device_tracker.rst b/docs/source/api/device_tracker.rst new file mode 100644 index 0000000000000..e3d65174815b1 --- /dev/null +++ b/docs/source/api/device_tracker.rst @@ -0,0 +1,10 @@ +.. _components_device_tracker_module: + +:mod:`homeassistant.components.device_tracker` +---------------------------------------------- + +.. automodule:: homeassistant.components.device_tracker + :members: + +.. autoclass:: Device + :members: diff --git a/docs/source/api/helpers.rst b/docs/source/api/helpers.rst new file mode 100644 index 0000000000000..af186fb1341ee --- /dev/null +++ b/docs/source/api/helpers.rst @@ -0,0 +1,118 @@ +homeassistant.helpers package +============================= + +Submodules +---------- + +homeassistant.helpers.condition module +-------------------------------------- + +.. automodule:: homeassistant.helpers.condition + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.config_validation module +---------------------------------------------- + +.. automodule:: homeassistant.helpers.config_validation + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.discovery module +-------------------------------------- + +.. automodule:: homeassistant.helpers.discovery + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.entity module +----------------------------------- + +.. automodule:: homeassistant.helpers.entity + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.entity_component module +--------------------------------------------- + +.. automodule:: homeassistant.helpers.entity_component + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.event module +---------------------------------- + +.. automodule:: homeassistant.helpers.event + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.event_decorators module +--------------------------------------------- + +.. automodule:: homeassistant.helpers.event_decorators + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.location module +------------------------------------- + +.. automodule:: homeassistant.helpers.location + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.script module +----------------------------------- + +.. automodule:: homeassistant.helpers.script + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.service module +------------------------------------ + +.. automodule:: homeassistant.helpers.service + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.state module +---------------------------------- + +.. automodule:: homeassistant.helpers.state + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.template module +------------------------------------- + +.. automodule:: homeassistant.helpers.template + :members: + :undoc-members: + :show-inheritance: + +homeassistant.helpers.typing module +----------------------------------- + +.. automodule:: homeassistant.helpers.typing + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: homeassistant.helpers + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/homeassistant.rst b/docs/source/api/homeassistant.rst new file mode 100644 index 0000000000000..f5ff069451d1a --- /dev/null +++ b/docs/source/api/homeassistant.rst @@ -0,0 +1,78 @@ +homeassistant package +===================== + +Subpackages +----------- + +.. toctree:: + + helpers + util + +Submodules +---------- + +bootstrap module +------------------------------ + +.. automodule:: homeassistant.bootstrap + :members: + :undoc-members: + :show-inheritance: + +config module +--------------------------- + +.. automodule:: homeassistant.config + :members: + :undoc-members: + :show-inheritance: + +const module +-------------------------- + +.. automodule:: homeassistant.const + :members: + :undoc-members: + :show-inheritance: + +core module +------------------------- + +.. automodule:: homeassistant.core + :members: + :undoc-members: + :show-inheritance: + +exceptions module +------------------------------- + +.. automodule:: homeassistant.exceptions + :members: + :undoc-members: + :show-inheritance: + +loader module +--------------------------- + +.. automodule:: homeassistant.loader + :members: + :undoc-members: + :show-inheritance: + +remote module +--------------------------- + +.. automodule:: homeassistant.remote + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: homeassistant + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/api/util.rst b/docs/source/api/util.rst new file mode 100644 index 0000000000000..7d6a22dbc0b73 --- /dev/null +++ b/docs/source/api/util.rst @@ -0,0 +1,78 @@ +homeassistant.util package +========================== + +Submodules +---------- + +homeassistant.util.color module +------------------------------- + +.. automodule:: homeassistant.util.color + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.distance module +---------------------------------- + +.. automodule:: homeassistant.util.distance + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.dt module +---------------------------- + +.. automodule:: homeassistant.util.dt + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.location module +---------------------------------- + +.. automodule:: homeassistant.util.location + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.package module +--------------------------------- + +.. automodule:: homeassistant.util.package + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.temperature module +------------------------------------- + +.. automodule:: homeassistant.util.temperature + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.unit_system module +------------------------------------- + +.. automodule:: homeassistant.util.unit_system + :members: + :undoc-members: + :show-inheritance: + +homeassistant.util.yaml module +------------------------------ + +.. automodule:: homeassistant.util.yaml + :members: + :undoc-members: + :show-inheritance: + + +Module contents +--------------- + +.. automodule:: homeassistant.util + :members: + :undoc-members: + :show-inheritance: diff --git a/docs/source/conf.py b/docs/source/conf.py index 4ca74060aada3..66bce1e895a3c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -17,16 +17,19 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) +import sys, os +from os.path import relpath, dirname +import inspect + +sys.path.insert(0, os.path.abspath('_ext')) +sys.path.insert(0, os.path.abspath('../homeassistant')) from homeassistant.const import (__version__, __short_version__, PROJECT_NAME, PROJECT_LONG_DESCRIPTION, PROJECT_URL, PROJECT_COPYRIGHT, PROJECT_AUTHOR, PROJECT_GITHUB_USERNAME, PROJECT_GITHUB_REPOSITORY, PYPI_URL, - GITHUB_URL) + GITHUB_PATH, GITHUB_URL) # -- General configuration ------------------------------------------------ @@ -39,8 +42,9 @@ # ones. extensions = [ 'sphinx.ext.autodoc', - 'sphinx.ext.viewcode', - 'sphinx_autodoc_typehints', + 'sphinx.ext.linkcode', + 'sphinx_autodoc_annotation', + 'edit_on_github' ] # Add any paths that contain templates here, relative to this directory. @@ -73,6 +77,48 @@ # The full version, including alpha/beta/rc tags. release = __version__ +code_branch = 'dev' if 'dev' in __version__ else 'master' + +# Edit on Github config +edit_on_github_project = GITHUB_PATH +edit_on_github_branch = code_branch +edit_on_github_src_path = 'docs/source/' + +def linkcode_resolve(domain, info): + """ + Determine the URL corresponding to Python object + """ + if domain != 'py': + return None + modname = info['module'] + fullname = info['fullname'] + submod = sys.modules.get(modname) + if submod is None: + return None + obj = submod + for part in fullname.split('.'): + try: + obj = getattr(obj, part) + except: + return None + try: + fn = inspect.getsourcefile(obj) + except: + fn = None + if not fn: + return None + try: + source, lineno = inspect.findsource(obj) + except: + lineno = None + if lineno: + linespec = "#L%d" % (lineno + 1) + else: + linespec = "" + fn = relpath(fn, start='../') + + return '{}/blob/{}/{}{}'.format(GITHUB_URL, code_branch, fn, linespec) + # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. # @@ -148,13 +194,6 @@ 'travis_button': True, 'touch_icon': 'logo-apple.png', # 'fixed_sidebar': True, # Re-enable when we have more content - 'extra_nav_links': { - '🏡 Homepage': PROJECT_URL, - '📌 Community Forums': 'https://community.home-assistant.io', - '💬 Gitter': 'https://gitter.im/home-assistant/home-assistant', - '🚀 GitHub': GITHUB_URL, - '💾 Download Releases': PYPI_URL, - } } # Add any paths that contain custom themes here, relative to this directory. @@ -208,9 +247,11 @@ html_sidebars = { '**': [ 'about.html', - 'navigation.html', - 'relations.html', + 'links.html', 'searchbox.html', + 'sourcelink.html', + 'navigation.html', + 'relations.html' ] } diff --git a/homeassistant/const.py b/homeassistant/const.py index c367792852af6..7b61daa1c8eaa 100644 --- a/homeassistant/const.py +++ b/homeassistant/const.py @@ -11,7 +11,7 @@ PROJECT_PACKAGE_NAME = 'homeassistant' PROJECT_LICENSE = 'MIT License' PROJECT_AUTHOR = 'The Home Assistant Authors' -PROJECT_COPYRIGHT = '2016, {}'.format(PROJECT_AUTHOR) +PROJECT_COPYRIGHT = ' 2016, {}'.format(PROJECT_AUTHOR) PROJECT_URL = 'https://home-assistant.io/' PROJECT_EMAIL = 'hello@home-assistant.io' PROJECT_DESCRIPTION = ('Open-source home automation platform ' @@ -34,8 +34,9 @@ PROJECT_GITHUB_REPOSITORY = 'home-assistant' PYPI_URL = 'https://pypi.python.org/pypi/{}'.format(PROJECT_PACKAGE_NAME) -GITHUB_URL = 'https://github.com/{}/{}'.format(PROJECT_GITHUB_USERNAME, - PROJECT_GITHUB_REPOSITORY) +GITHUB_PATH = '{}/{}'.format(PROJECT_GITHUB_USERNAME, + PROJECT_GITHUB_REPOSITORY) +GITHUB_URL = 'https://github.com/{}'.format(GITHUB_PATH) PLATFORM_FORMAT = '{}.{}'