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/tests.py

@@ -46,6 +46,9 @@ class GalaxyTest(TestCase):
         self.com = User.objects.get(username="comunity")
 
     def test_user_self_score(self):
+        """
+        Test that individual user scores are correct
+        """
         with self.assertNumQueries(8):
             self.assertEqual(Galaxy.compute_user_score(self.root), 9)
             self.assertEqual(Galaxy.compute_user_score(self.skia), 10)
@@ -57,6 +60,10 @@ class GalaxyTest(TestCase):
             self.assertEqual(Galaxy.compute_user_score(self.com), 1)
 
     def test_users_score(self):
+        """
+        Test on the default dataset generated by the `populate` command
+        that the relation scores are correct
+        """
         expected_scores = {
             "krophil": {
                 "comunity": {"clubs": 0, "family": 0, "pictures": 0, "score": 0},
@@ -117,15 +124,13 @@ class GalaxyTest(TestCase):
             while len(users) > 0:
                 user1 = users.pop(0)
                 for user2 in users:
-                    score, family, pictures, clubs = Galaxy.compute_users_score(
-                        user1, user2
-                    )
+                    score = Galaxy.compute_users_score(user1, user2)
                     u1 = computed_scores.get(user1.username, {})
                     u1[user2.username] = {
-                        "score": score,
-                        "family": family,
-                        "pictures": pictures,
-                        "clubs": clubs,
+                        "score": sum(score),
+                        "family": score.family,
+                        "pictures": score.pictures,
+                        "clubs": score.clubs,
                     }
                     computed_scores[user1.username] = u1
 
@@ -133,6 +138,9 @@ class GalaxyTest(TestCase):
         self.assertDictEqual(expected_scores, computed_scores)
 
     def test_page_is_citizen(self):
+        """
+        Test that users can access the galaxy page of users who are citizens
+        """
         with self.assertNumQueries(59):
             galaxy = Galaxy.objects.create()
             galaxy.rule(0)  # We want all users here
@@ -145,6 +153,10 @@ class GalaxyTest(TestCase):
         )
 
     def test_page_not_citizen(self):
+        """
+        Test that trying to access the galaxy page of a user who is not
+        citizens return a 404
+        """
         galaxy = Galaxy.objects.create()
         galaxy.rule(0)  # We want all users here
         self.client.login(username="root", password="plop")
@@ -152,6 +164,10 @@ class GalaxyTest(TestCase):
         self.assertEquals(response.status_code, 404)
 
     def test_full_galaxy_state(self):
+        """
+        Test on the more complex dataset generated by the `generate_galaxy_test_data`
+        command that the relation scores are correct
+        """
         call_command("generate_galaxy_test_data", "-v", "0")
         galaxy = Galaxy.objects.create()
         galaxy.rule(26)  # We want a fast test