Refactor API documentation (#33217)

* Upgrade Sphinx to 2.4.4

* Refactor API documentation

* Remove left-over

* Remove Markdown from docstring

* Update titels

docs/source/api/auth.rst

@@ -0,0 +1,29 @@
+:mod:`homeassistant.auth`
+=========================
+
+.. automodule:: homeassistant.auth
+    :members:
+
+homeassistant.auth.auth\_store
+------------------------------
+
+.. automodule:: homeassistant.auth.auth_store
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.auth.const
+------------------------
+
+.. automodule:: homeassistant.auth.const
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.auth.models
+-------------------------
+
+.. automodule:: homeassistant.auth.models
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/api/bootstrap.rst

@@ -1,7 +1,7 @@
 .. _bootstrap_module:
 
 :mod:`homeassistant.bootstrap`
--------------------------
+------------------------------
 
 .. automodule:: homeassistant.bootstrap
     :members:

docs/source/api/components.rst

@@ -0,0 +1,170 @@
+:mod:`homeassistant.components`
+===============================
+
+air\_quality
+--------------------------------------------
+
+.. automodule:: homeassistant.components.air_quality
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+alarm\_control\_panel
+--------------------------------------------
+
+.. automodule:: homeassistant.components.alarm_control_panel
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+binary\_sensor
+--------------------------------------------
+
+.. automodule:: homeassistant.components.binary_sensor
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+camera
+---------------------------
+
+.. automodule:: homeassistant.components.camera
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+calendar
+---------------------------
+
+.. automodule:: homeassistant.components.calendar
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+climate
+---------------------------
+
+.. automodule:: homeassistant.components.climate
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+conversation
+---------------------------
+
+.. automodule:: homeassistant.components.conversation
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+cover
+---------------------------
+
+.. automodule:: homeassistant.components.cover
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+device\_tracker
+---------------------------
+
+.. automodule:: homeassistant.components.device_tracker
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+fan
+---------------------------
+
+.. automodule:: homeassistant.components.fan
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+light
+---------------------------
+
+.. automodule:: homeassistant.components.light
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+lock
+---------------------------
+
+.. automodule:: homeassistant.components.lock
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+media\_player
+---------------------------
+
+.. automodule:: homeassistant.components.media_player
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+notify
+---------------------------
+
+.. automodule:: homeassistant.components.notify
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+remote
+---------------------------
+
+.. automodule:: homeassistant.components.remote
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+switch
+---------------------------
+
+.. automodule:: homeassistant.components.switch
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+sensor
+-------------------------------------
+
+.. automodule:: homeassistant.components.sensor
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+vacuum
+-------------------------------------
+
+.. automodule:: homeassistant.components.vacuum
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+water\_heater
+-------------------------------------
+
+.. automodule:: homeassistant.components.water_heater
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+weather
+---------------------------
+
+.. automodule:: homeassistant.components.weather
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+webhook
+---------------------------
+
+.. automodule:: homeassistant.components.webhook
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/api/config_entries.rst

@@ -0,0 +1,7 @@
+.. _config_entries_module:
+
+:mod:`homeassistant.config_entries`
+-----------------------------------
+
+.. automodule:: homeassistant.config_entries
+    :members:

docs/source/api/core.rst

@@ -4,35 +4,4 @@
 -------------------------
 
 .. automodule:: homeassistant.core
-
-.. autoclass:: Config
     :members:
-
-.. autoclass:: Event
-    :members:
-
-.. autoclass:: EventBus
-    :members:
-
-.. autoclass:: HomeAssistant
-    :members:
-
-.. autoclass:: State
-    :members:
-
-.. autoclass:: StateMachine
-    :members:
-
-.. autoclass:: ServiceCall
-    :members:
-
-.. autoclass:: ServiceRegistry
-    :members:
-
-Module contents
----------------
-
-.. automodule:: homeassistant.core
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/api/data_entry_flow.rst

@@ -0,0 +1,7 @@
+.. _data_entry_flow_module:
+
+:mod:`homeassistant.data_entry_flow`
+-----------------------------
+
+.. automodule:: homeassistant.data_entry_flow
+    :members:

docs/source/api/device_tracker.rst

@@ -1,10 +0,0 @@
-.. _components_device_tracker_module:
-
-:mod:`homeassistant.components.device_tracker`
-----------------------------------------------
-
-.. automodule:: homeassistant.components.device_tracker
-    :members:
-
-.. autoclass:: Device
-    :members:

docs/source/api/entity.rst

@@ -1,12 +0,0 @@
-.. _helpers_entity_module:
-
-:mod:`homeassistant.helpers.entity`
------------------------------------
-
-.. automodule:: homeassistant.helpers.entity
-
-.. autoclass:: Entity
-    :members:
-
-.. autoclass:: ToggleEntity
-    :members:

docs/source/api/event.rst

@@ -1,20 +0,0 @@
-.. _helpers_event_module:
-
-:mod:`homeassistant.helpers.event`
-----------------------------------
-
-.. automodule:: homeassistant.helpers.event
-
-.. autofunction:: track_state_change
-
-.. autofunction:: track_point_in_time
-
-.. autofunction:: track_point_in_utc_time
-
-.. autofunction:: track_sunrise
-
-.. autofunction:: track_sunset
-
-.. autofunction:: track_utc_time_change
-
-.. autofunction:: track_time_change

docs/source/api/exceptions.rst

@@ -0,0 +1,7 @@
+.. _exceptions_module:
+
+:mod:`homeassistant.exceptions`
+-------------------------------
+
+.. automodule:: homeassistant.exceptions
+    :members:

docs/source/api/helpers.rst

@@ -1,287 +1,335 @@
-homeassistant.helpers package
+:mod:`homeassistant.helpers`
-=============================
+============================
 
-Submodules
+.. automodule:: homeassistant.helpers
-----------
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
-homeassistant.helpers.aiohttp_client module
+homeassistant.helpers.aiohttp\_client
--------------------------------------------
+-------------------------------------
 
 .. automodule:: homeassistant.helpers.aiohttp_client
    :members:
    :undoc-members:
    :show-inheritance:
 
-
+homeassistant.helpers.area\_registry
-homeassistant.helpers.area_registry module
+------------------------------------
-------------------------------------------
 
 .. automodule:: homeassistant.helpers.area_registry
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.condition module
+homeassistant.helpers.check\_config
---------------------------------------
+-----------------------------------
+
+.. automodule:: homeassistant.helpers.check_config
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.collection
+--------------------------------
+
+.. automodule:: homeassistant.helpers.collection
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.condition
+-------------------------------
 
 .. automodule:: homeassistant.helpers.condition
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.config_entry_flow module
+homeassistant.helpers.config\_entry\_flow
-----------------------------------------------
+-----------------------------------------
 
 .. automodule:: homeassistant.helpers.config_entry_flow
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.config_validation module
+homeassistant.helpers.config\_entry\_oauth2\_flow
-----------------------------------------------
+-------------------------------------------------
+
+.. automodule:: homeassistant.helpers.config_entry_oauth2_flow
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.config\_validation
+----------------------------------------
 
 .. automodule:: homeassistant.helpers.config_validation
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.data_entry_flow module
+homeassistant.helpers.data\_entry\_flow
---------------------------------------------
+---------------------------------------
 
 .. automodule:: homeassistant.helpers.data_entry_flow
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.deprecation module
+homeassistant.helpers.debounce
-----------------------------------------
+------------------------------
+
+.. automodule:: homeassistant.helpers.debounce
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.deprecation
+---------------------------------
 
 .. automodule:: homeassistant.helpers.deprecation
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.device_registry module
+homeassistant.helpers.device\_registry
---------------------------------------------
+--------------------------------------
 
 .. automodule:: homeassistant.helpers.device_registry
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.discovery module
+homeassistant.helpers.discovery
---------------------------------------
+-------------------------------
 
 .. automodule:: homeassistant.helpers.discovery
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.dispatcher module
+homeassistant.helpers.dispatcher
----------------------------------------
+--------------------------------
 
 .. automodule:: homeassistant.helpers.dispatcher
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entity module
+homeassistant.helpers.entity
------------------------------------
+----------------------------
 
 .. automodule:: homeassistant.helpers.entity
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entity_component module
+homeassistant.helpers.entity\_component
----------------------------------------------
+---------------------------------------
 
 .. automodule:: homeassistant.helpers.entity_component
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entity_platform module
+homeassistant.helpers.entity\_platform
---------------------------------------------
+--------------------------------------
 
 .. automodule:: homeassistant.helpers.entity_platform
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entity_registry module
+homeassistant.helpers.entity\_registry
---------------------------------------------
+--------------------------------------
 
 .. automodule:: homeassistant.helpers.entity_registry
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entity_values module
+homeassistant.helpers.entity\_values
-------------------------------------------
+------------------------------------
 
 .. automodule:: homeassistant.helpers.entity_values
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.entityfilter module
+homeassistant.helpers.entityfilter
------------------------------------------
+----------------------------------
 
 .. automodule:: homeassistant.helpers.entityfilter
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.event module
+homeassistant.helpers.event
-----------------------------------
+---------------------------
 
 .. automodule:: homeassistant.helpers.event
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.icon module
+homeassistant.helpers.icon
----------------------------------
+--------------------------
 
 .. automodule:: homeassistant.helpers.icon
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.intent module
+homeassistant.helpers.integration\_platform
------------------------------------
+-------------------------------------------
+
+.. automodule:: homeassistant.helpers.integration_platform
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.intent
+----------------------------
 
 .. automodule:: homeassistant.helpers.intent
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.json module
+homeassistant.helpers.json
----------------------------------
+--------------------------
 
 .. automodule:: homeassistant.helpers.json
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.location module
+homeassistant.helpers.location
--------------------------------------
+------------------------------
 
 .. automodule:: homeassistant.helpers.location
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.logging module
+homeassistant.helpers.logging
-------------------------------------
+-----------------------------
 
 .. automodule:: homeassistant.helpers.logging
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.restore_state module
+homeassistant.helpers.network
-------------------------------------------
+-----------------------------
+
+.. automodule:: homeassistant.helpers.network
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.helpers.restore\_state
+------------------------------------
 
 .. automodule:: homeassistant.helpers.restore_state
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.script module
+homeassistant.helpers.script
------------------------------------
+----------------------------
 
 .. automodule:: homeassistant.helpers.script
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.service module
+homeassistant.helpers.service
-------------------------------------
+-----------------------------
 
 .. automodule:: homeassistant.helpers.service
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.signal module
+homeassistant.helpers.signal
------------------------------------
+-----------------------------
 
 .. automodule:: homeassistant.helpers.signal
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.state module
+homeassistant.helpers.state
-----------------------------------
+---------------------------
 
 .. automodule:: homeassistant.helpers.state
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.storage module
+homeassistant.helpers.storage
-------------------------------------
+-----------------------------
 
 .. automodule:: homeassistant.helpers.storage
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.sun module
+homeassistant.helpers.sun
---------------------------------
+-------------------------
 
 .. automodule:: homeassistant.helpers.sun
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.system_info module
+homeassistant.helpers.system\_info
-----------------------------------------
+----------------------------------
 
 .. automodule:: homeassistant.helpers.system_info
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.temperature module
+homeassistant.helpers.temperature
-----------------------------------------
+---------------------------------
 
 .. automodule:: homeassistant.helpers.temperature
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.template module
+homeassistant.helpers.template
--------------------------------------
+------------------------------
 
 .. automodule:: homeassistant.helpers.template
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.translation module
+homeassistant.helpers.translation
------------------------------------------
+---------------------------------
 
 .. automodule:: homeassistant.helpers.translation
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.helpers.typing module
+homeassistant.helpers.typing
------------------------------------
+----------------------------
 
 .. automodule:: homeassistant.helpers.typing
    :members:
    :undoc-members:
    :show-inheritance:
 
+homeassistant.helpers.update\_coordinator
+-----------------------------------------
 
-Module contents
+.. automodule:: homeassistant.helpers.update_coordinator
----------------
-
-.. automodule:: homeassistant.helpers
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/api/homeassistant.rst

@@ -1,70 +0,0 @@
-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:
-
-
-Module contents
----------------
-
-.. automodule:: homeassistant
-    :members:
-    :undoc-members:
-    :show-inheritance:

docs/source/api/loader.rst

@@ -0,0 +1,7 @@
+.. _loader_module:
+
+:mod:`homeassistant.loader`
+---------------------------
+
+.. automodule:: homeassistant.loader
+    :members:

docs/source/api/util.rst

@@ -1,86 +1,159 @@
-homeassistant.util package
+:mod:`homeassistant.util`
-==========================
+=========================
 
-Submodules
+.. automodule:: homeassistant.util
-----------
-
-homeassistant.util.async_ module
--------------------------------
-
-.. automodule:: homeassistant.util.async_
    :members:
    :undoc-members:
    :show-inheritance:
 
-homeassistant.util.color module
+homeassistant.util.yaml
--------------------------------
+-----------------------
-
-.. 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:
 
+homeassistant.util.aiohttp
+--------------------------
 
-Module contents
+.. automodule:: homeassistant.util.aiohttp
----------------
+   :members:
-
+   :undoc-members:
-.. automodule:: homeassistant.util
+   :show-inheritance:
+
+homeassistant.util.async\_
+--------------------------
+
+.. automodule:: homeassistant.util.async_
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.color
+------------------------
+
+.. automodule:: homeassistant.util.color
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.decorator
+----------------------------
+
+.. automodule:: homeassistant.util.decorator
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.distance
+---------------------------
+
+.. automodule:: homeassistant.util.distance
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.dt
+---------------------
+
+.. automodule:: homeassistant.util.dt
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.json
+-----------------------
+
+.. automodule:: homeassistant.util.json
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.location
+---------------------------
+
+.. automodule:: homeassistant.util.location
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.logging
+--------------------------
+
+.. automodule:: homeassistant.util.logging
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.network
+--------------------------
+
+.. automodule:: homeassistant.util.network
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.package
+--------------------------
+
+.. automodule:: homeassistant.util.package
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.pil
+----------------------
+
+.. automodule:: homeassistant.util.pil
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.pressure
+---------------------------
+
+.. automodule:: homeassistant.util.pressure
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.ruamel\_yaml
+-------------------------------
+
+.. automodule:: homeassistant.util.ruamel_yaml
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.ssl
+----------------------
+
+.. automodule:: homeassistant.util.ssl
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.temperature
+------------------------------
+
+.. automodule:: homeassistant.util.temperature
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.unit\_system
+-------------------------------
+
+.. automodule:: homeassistant.util.unit_system
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+homeassistant.util.volume
+-------------------------
+
+.. automodule:: homeassistant.util.volume
    :members:
    :undoc-members:
    :show-inheritance:

docs/source/conf.py

@@ -26,7 +26,7 @@ from homeassistant.const import __short_version__, __version__
 PROJECT_NAME = 'Home Assistant'
 PROJECT_PACKAGE_NAME = 'homeassistant'
 PROJECT_AUTHOR = 'The Home Assistant Authors'
-PROJECT_COPYRIGHT = ' 2013-2018, {}'.format(PROJECT_AUTHOR)
+PROJECT_COPYRIGHT = ' 2013-2020, {}'.format(PROJECT_AUTHOR)
 PROJECT_LONG_DESCRIPTION = ('Home Assistant is an open-source '
                             'home automation platform running on Python 3. '
                             'Track and control all devices at home and '

homeassistant/helpers/config_entry_oauth2_flow.py

@@ -58,11 +58,10 @@ class AbstractOAuth2Implementation(ABC):
 
         Pass external data in with:
 
-        ```python
         await hass.config_entries.flow.async_configure(
             flow_id=flow_id, user_input=external_data
         )
-        ```
+
         """
 
     @abstractmethod

requirements_docs.txt

@@ -1,3 +1,3 @@
-Sphinx==2.3.1
+Sphinx==2.4.4
 sphinx-autodoc-typehints==1.10.3
 sphinx-autodoc-annotation==1.0.post1