Update docs for all classes

Add module documentation too

alignak_app/__init__.py

@@ -22,7 +22,9 @@
 """
     Alignak App
 
-    This module is an Alignak App Indicator
+    This module is an appindicator for Alignak.
+
+    Application notify you when you have hosts / services DOWN. You'll be notified on your desktop and you can reach your Hosts and Services on your WebUI from this application.
 """
 
 # Application version and manifest

alignak_app/alignak_data.py

@@ -27,9 +27,9 @@
 
 class AlignakData(object):
     """
-        Alignak Bridge
+        Alignak Data
 
-        This class collect informations with Backend-Client and return essential things for
+        This class collect informations with Backend-Client and return essential data for
         Alignak-App.
     """
 
@@ -39,6 +39,12 @@ def __init__(self):
         self.backend = None
 
     def log_to_backend(self, config):
+        """
+        Connect to backend with your credentials.
+
+        :param config: parser config who contains settings
+        :type config: :class:`~configparser.ConfigParser`
+        """
         # Credentials
         username = config.get('Backend', 'username')
         password = config.get('Backend', 'password')
@@ -53,6 +59,10 @@ def log_to_backend(self, config):
                      '\n - Please check backend state, url or your credentials.')
 
     def get_host_state(self):
+        """
+        Collect state of Hosts, via backend API.
+
+        """
         # Request
         try:
             params = {'where': json.dumps({'_is_template': False})}
@@ -68,6 +78,10 @@ def get_host_state(self):
         return self.current_hosts
 
     def get_service_state(self):
+        """
+        Collect state of Services, via backend API.
+
+        """
         # Request
         try:
             params = {'where': json.dumps({'_is_template': False})}

alignak_app/app_menu.py

@@ -33,7 +33,8 @@ class AppMenu(object):
     def __init__(self, config):
         """
 
-        :param config: config file of AlignakApp
+        :param config: parser config who contains settings
+        :type config: :class:`~configparser.ConfigParser`
         """
         self.hosts_up_item = None
         self.hosts_down_item = None
@@ -47,7 +48,8 @@ def __init__(self, config):
 
     def build_items(self):
         """
-        Initialize and create each items
+        Initialize and create each item of menu.
+
         """
         self.hosts_up_item = self.create_items('h_up')
         self.hosts_down_item = self.create_items('h_down')
@@ -62,8 +64,10 @@ def build_items(self):
     def create_items(self, style):
         """
         Create each item for menu. Possible values: down, up, None
+
         :param style: style of menu to create
-        :return: gtk.ImageMenuItem
+        :type style: str
+        :return: :class:`~gi.repository.gtk.ImageMenuItem`
         """
         item = Gtk.ImageMenuItem('')
         img = Gtk.Image()
@@ -103,8 +107,10 @@ def build_menu(self, menu):
         """
         Create Main Menu with its Items. Make a first check for Hosts
 
-        :return: menu
-        :rtype: gtk.Menu
+        :param menu: Gtk Menu
+        :type menu: :class:`~gi.repository.Gtk.Menu`
+        :return: menu with all items.
+        :rtype: :class:`~gi.repository.gtk.Menu`
         """
         # Separators
         separator_host = Gtk.SeparatorMenuItem()
@@ -126,9 +132,10 @@ def build_menu(self, menu):
 
     def open_url(self, item):
         """
-        Add a web link on every menu
+        Add a link to WebUI on every menu
 
         :param item: items of Gtk menu
+        :type item: :class:`~gi.repository.Gtk.ImageMenuItem`
         """
         assert isinstance(item, Gtk.ImageMenuItem)
 
@@ -159,7 +166,8 @@ def quit_app(item):
         """
         Quit application
 
-        :param item: item of Gtk menu
+        :param item: item of Gtk menu. Required by :class:`~Gtk.ImageMenuItem().connect`.
+        :type item: :class:`~Gtk.ImageMenuItem`
         """
         assert isinstance(item, Gtk.ImageMenuItem)
 
@@ -171,7 +179,9 @@ def update_hosts_menu(self, hosts_states, services_states):
         Update items Menu
 
         :param hosts_states: number of hosts UP, DOWN or UNREACHABLE
+        :type hosts_states: dict
         :param services_states: number of services OK, CRITICAL, WARNING or UNKNOWN
+        :type services_states: dict
         """
 
         self.hosts_up_item.set_label(

alignak_app/application.py

@@ -55,7 +55,9 @@ def __init__(self):
     def main(self):
         """
         Create indicator, menu and main Gtk
+
         """
+
         # Create Menus
         self.app_menu = AppMenu(self.config)
         self.app_menu.build_items()
@@ -69,16 +71,22 @@ def main(self):
         indicator.set_menu(self.create_menu())
 
     def read_configuration(self):
+        """
+        Read the configuration file.
+
+        """
+
         self.config = cfg.ConfigParser()
         self.config.read('/etc/alignak_app/settings.cfg')
 
     def set_indicator(self):
         """
         Initialize a new Indicator and his notifications
 
-        :return: indicator
-        :rtype: Indicator
+        :return: Indicator
+        :rtype: :py:class:`~gi.repository.AppIndicator3.Indicator`
         """
+
         # Define ID and build Indicator
         app_id = 'appalignak'
         img = os.path.abspath(
@@ -100,6 +108,12 @@ def set_indicator(self):
         return self.indicator
 
     def create_menu(self):
+        """
+        Create the menu, and get first states.
+
+        :return: menu
+        :rtype: :class:`~gi.repository.Gtk.Menu()`
+        """
         menu = Gtk.Menu()
         self.app_menu.build_menu(menu)
 
@@ -112,6 +126,7 @@ def create_menu(self):
     def start_process(self):
         """
         Start process loop.
+
         """
         check_interval = int(self.config.get('Alignak-App', 'check_interval'))
         GLib.timeout_add_seconds(check_interval, self.notify_change)
@@ -121,7 +136,9 @@ def notify_change(self):
         Send a notification if DOWN
 
         :return: True to continue process
+        :rtype: bool
         """
+
         hosts_states, services_states = self.get_state()
 
         message = "Info: all is OK.)"
@@ -177,7 +194,8 @@ def get_state(self):
         """
         Check the hosts states.
 
-        :return: number of hosts and services UP, UNKNOWN and DOWN
+        :return: number of hosts and services UP, UNKNOWN and DOWN in two dict.
+        :rtype: dict
         """
 
         # Dicts for states
@@ -218,6 +236,13 @@ def get_state(self):
         return hosts_states, services_states
 
     def change_icon(self, state):
+        """
+        Change icon depending on the hosts / services status
+
+        :param state: icon wanted
+        :type state: str
+        """
+
         if "ok" in state:
             icon = self.config.get('Config', 'ok')
         elif "alert" in state:
@@ -237,7 +262,8 @@ def change_icon(self, state):
 
     def run(self):
         """
-        Run application
+        Run application. read configuration, create menus and start process.
+
         """
 
         # Read settings.cfg

alignak_app/launch.py

@@ -27,8 +27,9 @@
 
 def launch():
     """
-        Launch Alignak-App.
+        Check environment and launch Alignak-App.
     """
+
     # Actually, we must verify we are in DESKTOP_SESSION or not
     try:
         os.environ['DESKTOP_SESSION']

docs/alignak_app.rst

@@ -0,0 +1,49 @@
+.. _alignak_app:
+
+Alignak_App Package
+===================
+
+Module contents
+---------------
+
+.. automodule:: alignak_app
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+Submodules
+----------
+
+alignak_app.alignak_data
+------------------------
+
+.. automodule:: alignak_app.alignak_data
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+alignak_app.app_menu
+--------------------
+
+.. automodule:: alignak_app.app_menu
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+alignak_app.application
+-----------------------
+
+.. automodule:: alignak_app.application
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+alignak_app.launch
+------------------
+
+.. automodule:: alignak_app.launch
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+

docs/conf.py

@@ -16,9 +16,9 @@
 # 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 os
+import sys
+sys.path.insert(0, os.path.abspath('../'))
 
 # -- General configuration ------------------------------------------------
 
@@ -29,10 +29,11 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = []
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
@@ -57,9 +58,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1'
+version = u'0.2'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1.0'
+release = u'0.2.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/index.rst

@@ -15,6 +15,7 @@ Documentation content:
    install
    config
    launch
+   alignak_app
 
 
 Indices and tables