Reference docs

blackmamba/__init__.py

@@ -1,4 +1,24 @@
 #!python3
+"""
+Black Mamba initialization module.
+
+Module is Python 3 compatible only.
+
+The only requirement is to call :func:`blackmamba.main`. Example:
+
+.. code-block:: python
+
+    import blackmamba
+    blackmamba.main()
+
+.. warning:: Do not add top level imports which depends on Pythonista modules. Module
+    must be importable on any other platform. Add these imports to specific functions
+    decorated with :obj:`blackmamba.system.Pythonista` and / or
+    :obj:`blackmamba.system.iOS`.
+
+Reference
+=========
+"""
 
 from blackmamba.log import info, error, get_level, set_level, ERROR
 import blackmamba.system as system
@@ -159,7 +179,9 @@ def _check_compatibility_and_updates():
 
 @system.Pythonista()
 @system.catch_exceptions
-def main(config=None):
+def _main(config=None):
+    # It's here because Sphinx doesn't show documentation for decorated
+    # functions
     from blackmamba.config import update_config_with_dict, get_config_value
     info('Black Mamba initialization...')
     if config:
@@ -171,5 +193,31 @@ def main(config=None):
     info('Black Mamba initialized')
 
 
+def main(config=None):
+    """
+    Black Mamba initialization.
+
+    Call this function from ``pythonista_startup.py`` (``site-packages-3``) file.
+
+    :param config: Optional dictionary, see :ref:`configuration`
+
+    Example:
+
+    .. code-block:: python
+
+        import blackmamba
+
+        config = {
+            'general': {
+                'jedi': True
+            }
+        }
+
+        blackmamba.main(config)
+
+    """
+    _main(config)
+
+
 if __name__ == '__main__':
     main()

blackmamba/config.py

@@ -1,6 +1,7 @@
 #!python3
 """
-I strongly suggests to check `config.py:_DEFAULTS <https://github.com/zrzka/blackmamba/blob/master/blackmamba/config.py>`_
+I strongly suggests to check
+`config.py:_DEFAULTS <https://github.com/zrzka/blackmamba/blob/master/blackmamba/config.py>`_
 from time to time. Just to check if this documentation isn't outdated.
 
 Sections

blackmamba/log.py

@@ -1,13 +1,37 @@
 #!python3
-'''Logging module.
+"""
+Logging module.
 
-Note:
-    This module must not introduce dependency on any other Black Mamba
-    modules and must be importable on any other platform as well.
+Why custom module instead of :mod:`logging`? Several reasons:
 
-Todo:
-    * Add exception logging support
-'''
+* not to interfere with Pythonista logging settings,
+* unable to convince Pythonista to use my colors,
+* etc.
+
+Default log level is ``INFO``. You can use :func:`blackmamba.log.set_level`
+to change effective log level. Available log levels are:
+
+* ``ERROR``
+* ``WARNING``
+* ``INFO``
+* ``DEBUG``
+* ``NOTSET``
+
+If you'd like to silent Black Mamba messages, it's recommended to set log
+level to ``ERROR``.
+
+.. code-block:: python
+
+    import blackmamba.log as log
+
+    log.set_level(log.ERROR)
+
+.. warning:: This module must not introduce dependency on any other Black Mamba
+    modules and must be importable on any other platform.
+
+Reference
+=========
+"""
 
 try:
     import console
@@ -29,10 +53,20 @@
 
 
 def get_level():
+    """
+    Return effective log level.
+
+    :return: Effective log level
+    """
     return _level
 
 
 def set_level(level):
+    """
+    Set effective log level.
+
+    :param level: Level to set
+    """
     global _level
     _level = level
 
@@ -52,16 +86,40 @@ def _log(level, *args, **kwargs):
 
 
 def debug(*args, **kwargs):
+    """
+    Log message with DEBUG level.
+
+    :param args: Passed to :func:`print`
+    :param kwargs: Passed to :func:`print`
+    """
     _log(DEBUG, *args, **kwargs)
 
 
 def info(*args, **kwargs):
+    """
+    Log message with INFO level.
+
+    :param args: Passed to :func:`print`
+    :param kwargs: Passed to :func:`print`
+    """
     _log(INFO, *args, **kwargs)
 
 
 def warn(*args, **kwargs):
+    """
+    Log message with WARNING level.
+
+    :param args: Passed to :func:`print`
+    :param kwargs: Passed to :func:`print`
+    """
     _log(WARNING, *args, **kwargs)
 
 
 def error(*args, **kwargs):
+    """
+    Log message with ERROR level.
+
+    :param args: Passed to :func:`print`
+    :param kwargs: Passed to :func:`print`
+    """
     _log(ERROR, *args, **kwargs)

blackmamba/system.py

@@ -1,10 +1,13 @@
 #!python3
-'''System info and decorators.
+"""
+System info and decorators.
 
-Note:
-    This module must not introduce dependency on any other Black Mamba
+.. warning:: This module must not introduce dependency on any other Black Mamba
     modules and must be importable on any other platform as well.
-'''
+
+Reference
+=========
+"""
 
 import sys
 import traceback
@@ -20,25 +23,25 @@
 # 3.1.1 beta, 311008
 
 PYTHONISTA = sys.platform == 'ios'
-'''bool: ``True`` if we're running within Pythonista or ``False``.'''
+"""bool: ``True`` if we're running within Pythonista or ``False``."""
 
 PYTHONISTA_VERSION = None
-'''str: Pythonista version or ``None`` if we're not within Pythonista.'''
+"""str: Pythonista version or ``None`` if we're not within Pythonista."""
 
 PYTHONISTA_BUNDLE_VERSION = None
-'''int: Pythonista bundle version or ``None`` if we're not within Pythonista.'''
+"""int: Pythonista bundle version or ``None`` if we're not within Pythonista."""
 
 PYTHONISTA_VERSION_TUPLE = None
-'''tuple(int): Pythonista version tuple (3, 1, 1) or ``None`` if we're not within Pythonista.'''
+"""tuple(int): Pythonista version tuple (3, 1, 1) or ``None`` if we're not within Pythonista."""
 
 IOS = sys.platform == 'ios'
-'''bool: ``True`` if we're running within iOS or ``False``.'''
+"""bool: ``True`` if we're running within iOS or ``False``."""
 
 IOS_VERSION = None
-'''str: iOS version or ``None`` if we're not within iOS.'''
+"""str: iOS version or ``None`` if we're not within iOS."""
 
 IOS_VERSION_TUPLE = None
-'''tuple(int): iOS version tuple (11, 0) or ``None`` if we're not within iOS.'''
+"""tuple(int): iOS version tuple (11, 0) or ``None`` if we're not within iOS."""
 
 
 def _version_tuple(version):
@@ -71,7 +74,7 @@ def _version_tuple(version):
         pass
 
 
-class _Available():
+class _Available:
     def __init__(self, from_version=None, to_version=None):
         if from_version and to_version:
             raise ValueError('Either from_version or to_version can be provided, not both')
@@ -104,9 +107,14 @@ def func(*args, **kwargs):
 
 
 class iOS(_Available):
-    '''Decorator to execute function under specific iOS versions.
+    """
+    Decorator to execute function under specific iOS versions.
+
+    Return value is return value of decorated function or ``None``
+    if iOS condition isn't met.
 
     Examples:
+
         Run function only within any iOS version::
 
             @iOS()
@@ -124,19 +132,24 @@ def run_me():
             @iOS(None, '11.0')  # or @iOS(to_version='11.0')
             def run_me():
                 pass
-    '''
+    """
     def version(self):
         return IOS_VERSION_TUPLE
 
 
 class Pythonista(_Available):
-    '''Decorator to execute function under specific Pythonista versions.
+    """
+    Decorator to execute function under specific Pythonista versions.
 
     By default, function is not executed under application extension.
-    You have to pass `appex=True` if you'd like to run some function
+    You have to pass ``appex=True`` if you'd like to run some function
     under appex as well.
 
+    Return value is return value of decorated function or ``None``
+    if Pythonista condition isn't met.
+
     Examples:
+
         Run function only within any Pythonista version::
 
             @Pythonista()
@@ -166,7 +179,7 @@ def run_me():
             @Pythonista(None, '3.2')  # or @Pythonista(to_version='3.2')
             def run_me():
                 pass
-    '''
+    """
     def __init__(self, from_version=None, to_version=None, appex=None):
         super().__init__(from_version, to_version)
         self._appex = appex
@@ -185,11 +198,15 @@ def version(self):
 
 
 def catch_exceptions(func):
-    '''Catches all ``Exception`` exceptions and writes info to console.
+    """
+    Decorator catching all ``Exception`` exceptions and writing info to console.
 
     Use this decorator for functions handling keyboard shortcuts,
     keyboard events, ... to avoid Pythonista crash.
-    '''
+
+    :param func: Function to decorate
+    :return: Return value of ``func``
+    """
     @functools.wraps(func)
     def new_func(*args, **kwargs):
         try: