write more extensive documentation

- add documentation to previously documented classes and functions and refactor some of the documented one, in accordance to the PEP257 and ReStructuredText standards ;
- add some type hints ;
- use a NamedTuple for the `Galaxy.compute_users_score` method instead of a raw tuple. Also change a little bit the logic in the function which call the latter ;
- add some additional parameter checks on a few functions ;
- change a little bit the logic of the log level setting for the galaxy related commands.

galaxy/management/commands/rule_galaxy.py

@@ -21,6 +21,7 @@
 # Place - Suite 330, Boston, MA 02111-1307, USA.
 #
 #
+import warnings
 
 from django.core.management.base import BaseCommand
 from django.db import connection
@@ -41,12 +42,15 @@ class Command(BaseCommand):
 
     def handle(self, *args, **options):
         logger = logging.getLogger("main")
-        if options["verbosity"] > 1:
+        if options["verbosity"] < 0 or 2 < options["verbosity"]:
+            warnings.warn("verbosity level should be between 0 and 2 included")
+
+        if options["verbosity"] == 2:
             logger.setLevel(logging.DEBUG)
-        elif options["verbosity"] > 0:
+        elif options["verbosity"] == 1:
             logger.setLevel(logging.INFO)
         else:
-            logger.setLevel(logging.NOTSET)
+            logger.setLevel(logging.ERROR)
 
         logger.info("The Galaxy is being ruled by the Sith.")
         galaxy = Galaxy.objects.create()