Add more documentation

doc/conf.py

@@ -282,6 +282,7 @@
 # Google Analytics configuration
 googleanalytics_id = 'UA-58471028-2'
 
-rst_epilog = '.. |pylease_version| replace:: %s' % version
+rst_epilog = '.. |pylease_version| replace:: %s\n\n' % version
+rst_epilog += '.. |pylease_named_command_suffix| replace:: %s\n\n' % pylease.cmd.NamedCommand._SUFFIX
 
-napoleon_google_docstring = True
+napoleon_google_docstring = True

doc/pages/config.rst

@@ -21,7 +21,6 @@ Following is the list of all configuration parameters with their descriptions.
 
         ``version-files = my_project/__init__.py, setup.py``
 
-.. _use-plugins:
 ``use-plugins``
     A list of external plugins to load. If you have installed ``example_plugin`` package in your Python environment, and want Pylease to
     use that plugin, you just need to add the ``example_plugin`` name to the list of this parameter.

doc/pages/ext.rst

@@ -25,9 +25,10 @@ The first step is inheriting the :class:`~pylease.ext.Extension` class, where yo
 which is an instance of :class:`~pylease.Pylease` class, and contains everything you need for your extension.
 
 Extending an existing Pylease command is done by adding a :class:`~pylease.cmd.task.BeforeTask` or :class:`~pylease.cmd.task.AfterTask`
-(or both) to it. What is needed to do is just implement those classes and add their instances to the command that is the subject of
-extension. For both :class:`~pylease.cmd.task.BeforeTask` and :class:`~pylease.cmd.task.AfterTask` you need to inherit and implement
-their :func:`~pylease.cmd.task.BeforeTask.execute` method, which must include the extension logic. Also, in case of
+(or both) to it using the :class:`~pylease.cmd.Command` methods :func:`~pylease.cmd.Command.add_before_task` and
+:func:`~pylease.cmd.Command.add_after_task`. What is needed to do is just implement those classes and add their instances to the command
+that is the subject of extension. For both :class:`~pylease.cmd.task.BeforeTask` and :class:`~pylease.cmd.task.AfterTask` you need to
+inherit and implement their :func:`~pylease.cmd.task.BeforeTask.execute` method, which must include the extension logic. Also, in case of
 :class:`~pylease.cmd.task.AfterTask`, you are provided with the :attr:`~pylease.cmd.task.AfterTask._command_result` attribute, which is
 the result returned by the command being extended.
 
@@ -43,5 +44,7 @@ Adding New Commands
 -------------------
 
 To add a new command to Pylease it is enough to implement a class by inheriting the :class:`~pylease.cmd.Command` class and add it to your
-package
-``__init__.py``.
+package ``__init__.py``. Implementing the :class:`~pylease.cmd.Command` class is implementing the
+:func:`~pylease.cmd.Command._process_command` method. As an additional convenience you can inherit the :class:`~pylease.cmd.NamedCommand`
+class instead.
+

doc/pages/ref.rst

@@ -27,4 +27,20 @@ Class Reference
 
         .. automethod:: execute
 
-        .. autoattribute:: _command_result
+        .. autoattribute:: _command_result
+
+.. automodule:: pylease.cmd
+
+    .. autoclass:: Command
+
+        .. automethod:: __init__
+
+        .. automethod:: _process_command
+
+        .. automethod:: add_before_task
+
+        .. automethod:: add_after_task
+
+    .. autoclass:: NamedCommand
+
+        .. automethod:: __init__

pylease/__init__.py

@@ -2,6 +2,9 @@
 from pylease.logger import LOGME as logme  # noqa
 import os
 
+import cmd
+import ext
+
 __version__ = '0.2'
 
 

pylease/cmd/__init__.py

@@ -16,8 +16,8 @@ class Command(object):
     # The whole logic of Pylease is centralized on the Command class,
     # thus it is reasonable to have more than seven instance attributes.
     """
-    This class is the main point of Pylease.
-    For adding new commands just inherit from this class and implement `_process_command` method.
+    This class is one of the main point of Pylease.
+    For adding new commands just inherit from this class and implement :func:`~pylease.cmd.Command._process_command` method.
     """
 
     __metaclass__ = ABCMeta
@@ -27,16 +27,17 @@ class Command(object):
 
     def __init__(self, lizy, name, description, rollback=None, requires_project=True):
         """
-        This constructor should be called from child classes at be supplied
-        with at least name and description.
-
-        :param lizy: The `lizy` object, which is initialized and passed by Pylease.
-        :param name: The name of the command, which will appear in the `usage` output
-        :param description: Description of the command
-        :param rollback: The rollback object that will be executed in case of failure during or after the command.
-        This parameter may be emitted if the command does not need a rollback, or may be set in the process of command
-        execution if it depends on some parameters during runtime.
-        :return:
+        This constructor should be called from child classes at least be supplied with at least ``name`` and ``description``.
+
+        Arguments:
+            lizy (pylease.Pylease): The `lizy` object, which is initialized and passed by Pylease.
+            name (str): The name of the command, which will appear in the `usage` output.
+            description (str): Description of the command which will also appear in the help message.
+            rollback (pylease.cmd.rollback.Rollback): The rollback object that will be executed in case of failure during or after the
+                command. This parameter may be emitted if the command does not need a rollback, or may be set in the process of command
+                execution using the :func:`~pylease.cmd.Command.enable_rollback` method, if it depends on some parameters during runtime.
+            requires_project (bool): Boolean indicating whether the command requires to operate on an existing project. E.g. the ``init``
+                command requires an empty directory.
         """
         super(Command, self).__init__()
 
@@ -56,6 +57,14 @@ def __init__(self, lizy, name, description, rollback=None, requires_project=True
 
     @abstractmethod
     def _process_command(self, lizy, args):
+        """
+        The method which should be implemented when inheriting the :class:`~pylease.cmd.Command`. All the command logic must go into this
+        method.
+
+        Arguments:
+            lizy (pylease.Pylease): The :class:`~pylease.Pylease` singleton.
+            args (argparse.Namespace): The arguments passed to the command line while invoking Pylease.
+        """
         pass  # pragma: no cover
 
     def __call__(self, args):
@@ -94,10 +103,22 @@ def init_all(cls, lizy):
                 command(lizy)
 
     def add_before_task(self, task):
+        """
+        Adds a :class:`~pylease.cmd.task.BeforeTask` to the :class:`~pylease.cmd.Command`.
+
+        Arguments:
+            task (pylease.cmd.task.BeforeTask): The task to be added.
+        """
         self.before_tasks.add(task)
         task.set_command(self)
 
     def add_after_task(self, task):
+        """
+        Adds a :class:`~pylease.cmd.task.AfterTask` to the :class:`~pylease.cmd.Command`.
+
+        Arguments:
+            task (pylease.cmd.task.AfterTask): The task to be added.
+        """
         self.after_tasks.add(task)
         task.set_command(self)
 
@@ -106,11 +127,20 @@ class NamedCommand(Command):
     # pylint: disable=W0223, too-few-public-methods
     # NamedCommand is also abstract
     # The number of public methods is reasonable for this kind of class
+    """
+    Same as the :class:`~pylease.cmd.Command` class, however this class enables a little taste of convenience. You can define a class
+    having name with a suffix "\ |pylease_named_command_suffix|\ " and it will automatically assign the prefix of the class name as the
+    command name.
+    """
 
     _SUFFIX = "Command"
     ignore_me = SubclassIgnoreMark('NamedCommand')
 
     def __init__(self, lizy, description, rollback=None, requires_project=True):
+        """
+        Same as :func:`~pylease.cmd.Command.__init__` of :class:`~pylease.cmd.Command` class, except that the ``name`` argument is passed
+        automatically.
+        """
         my_name = self.__class__.__name__
         name = my_name[:-(len(self._SUFFIX))].lower()