Work on cleaning up docs

evennia/contrib/tutorials/evadventure/README.md

@@ -1,19 +1,18 @@
 # EvAdventure
 
-Contrib by Griatch 2022
+Contrib by Griatch 2023-
 
 
 ```{warning}
-NOTE - this tutorial is WIP and NOT complete! It was put on hold to focus on
-releasing Evennia 1.0. You will still learn things from it, but don't expect
-perfection.
+NOTE - this tutorial is WIP and NOT complete yet! You will still learn
+things from it, but don't expect perfection.
 ```
 
 A complete example MUD using Evennia. This is the final result of what is
-implemented if you follow the Getting-Started tutorial. It's recommended
-that you follow the tutorial step by step and write your own code. But if
-you prefer you can also pick apart or use this as a starting point for your
-own game.
+implemented if you follow [Part 3 of the Getting-Started tutorial](Beginner-Tutorial-Part3-Overview).
+It's recommended that you follow the tutorial step by step and write your own
+code. But if you prefer you can also pick apart or use this as a starting point
+for your own game.
 
 ## Features
 

evennia/contrib/tutorials/evadventure/batchscripts/__init__.py

@@ -0,0 +1 @@
+# This file needs to be here for autodocs to pick up this folder/package

evennia/contrib/tutorials/evadventure/combat_base.py

@@ -3,13 +3,15 @@ EvAdventure Base combat utilities.
 
 This establishes the basic building blocks for combat:
 
-    - `CombatFailure` - exception for combat-specific errors.
-    - `CombatAction` (and subclasses) - classes encompassing all the working around an action.
-      They are initialized from 'action-dicts` - dictionaries with all the relevant data for the
-      particular invocation
-    - `CombatHandler` - base class for running a combat. Exactly how this is used depends on the
-      type of combat intended (twitch- or turn-based) so many details of this will be implemented
-      in child classes.
+- `CombatFailure` - exception for combat-specific errors.
+- `CombatAction` (and subclasses) - classes encompassing all the working around an action.
+  They are initialized from 'action-dicts` - dictionaries with all the relevant data for the
+  particular invocation
+- `CombatHandler` - base class for running a combat. Exactly how this is used depends on the
+  type of combat intended (twitch- or turn-based) so many details of this will be implemented
+  in child classes.
+
+----
 
 """
 
@@ -23,7 +25,7 @@ from . import rules
 
 class CombatFailure(RuntimeError):
     """
-    Some failure during actions.
+    Some failure during combat actions.
 
     """
 
@@ -98,28 +100,21 @@ class CombatAction:
 class CombatActionHold(CombatAction):
     """
     Action that does nothing.
-
-    Note:
-        Refer to as 'hold'
-
-    action_dict = {
-            "key": "hold"
-        }
+    ::
+        action_dict = {
+                "key": "hold"
+            }
     """
 
 
 class CombatActionAttack(CombatAction):
     """
     A regular attack, using a wielded weapon.
-
-    action-dict = {
-            "key": "attack",
-            "target": Character/Object
-        }
-
-    Note:
-        Refer to as 'attack'
-
+    ::
+        action-dict = {
+                "key": "attack",
+                "target": Character/Object
+            }
     """
 
     def execute(self):
@@ -140,19 +135,16 @@ class CombatActionStunt(CombatAction):
     target. Whenever performing a stunt that would affect another negatively (giving them
     disadvantage against an ally, or granting an advantage against them, we need to make a check
     first. We don't do a check if giving an advantage to an ally or ourselves.
-
-    action_dict = {
-           "key": "stunt",
-           "recipient": Character/NPC,
-           "target": Character/NPC,
-           "advantage": bool,  # if False, it's a disadvantage
-           "stunt_type": Ability,  # what ability (like STR, DEX etc) to use to perform this stunt.
-           "defense_type": Ability, # what ability to use to defend against (negative) effects of
-            this stunt.
-        }
-
-    Note:
-        refer to as 'stunt'.
+    ::
+        action_dict = {
+               "key": "stunt",
+               "recipient": Character/NPC,
+               "target": Character/NPC,
+               "advantage": bool,  # if False, it's a disadvantage
+               "stunt_type": Ability,  # what ability (like STR, DEX etc) to use to perform this stunt.
+               "defense_type": Ability, # what ability to use to defend against (negative) effects of
+                this stunt.
+            }
 
     """
 
@@ -209,16 +201,12 @@ class CombatActionUseItem(CombatAction):
     Use an item in combat. This is meant for one-off or limited-use items (so things like
     scrolls and potions, not swords and shields). If this is some sort of weapon or spell rune,
     we refer to the item to determine what to use for attack/defense rolls.
-
-    action_dict = {
-            "key": "use",
-            "item": Object
-            "target": Character/NPC/Object/None
-        }
-
-    Note:
-        Refer to as 'use'
-
+    ::
+        action_dict = {
+                "key": "use",
+                "item": Object
+                "target": Character/NPC/Object/None
+            }
     """
 
     def execute(self):
@@ -234,22 +222,17 @@ class CombatActionUseItem(CombatAction):
                 disadvantage=self.combathandler.has_disadvantage(user, target),
             )
             item.at_post_use(user, target)
-        # to back to idle after this
 
 
 class CombatActionWield(CombatAction):
     """
     Wield a new weapon (or spell) from your inventory. This will swap out the one you are currently
     wielding, if any.
-
-    action_dict = {
-            "key": "wield",
-            "item": Object
-        }
-
-    Note:
-        Refer to as 'wield'.
-
+    ::
+        action_dict = {
+                "key": "wield",
+                "item": Object
+            }
     """
 
     def execute(self):

evennia/contrib/tutorials/evadventure/tests/__init__.py

@@ -0,0 +1,4 @@
+"""
+Unit tests for EvAdventure components.
+
+"""

evennia/typeclasses/attributes.py

@@ -159,18 +159,7 @@ class InMemoryAttribute(IAttribute):
 
 class AttributeProperty:
     """
-    Attribute property descriptor. Allows for specifying Attributes as Django-like 'fields'
-    on the class level. Note that while one can set a lock on the Attribute,
-    there is no way to *check* said lock when accessing via the property - use
-    the full `AttributeHandler` if you need to do access checks. Note however that if you use the
-    full `AttributeHandler` to access this Attribute, the `at_get/at_set` methods on this class will
-    _not_ fire (because you are bypassing the `AttributeProperty` entirely in that case).
-
-    Example:
-    ::
-
-        class Character(DefaultCharacter):
-            foo = AttributeProperty(default="Bar")
+    AttributeProperty.
 
     """
 
@@ -178,6 +167,13 @@ class AttributeProperty:
 
     def __init__(self, default=None, category=None, strattr=False, lockstring="", autocreate=True):
         """
+        Allows for specifying Attributes as Django-like 'fields' on the class level. Note that while
+        one can set a lock on the Attribute, there is no way to *check* said lock when accessing via
+        the property - use the full `AttributeHandler` if you need to do access checks. Note however
+        that if you use the full `AttributeHandler` to access this Attribute, the `at_get/at_set`
+        methods on this class will _not_ fire (because you are bypassing the `AttributeProperty`
+        entirely in that case).
+
         Initialize an Attribute as a property descriptor.
 
         Keyword Args:
@@ -194,6 +190,11 @@ class AttributeProperty:
                 is explicitly assigned a value. This makes it more efficient while it retains
                 its default (there's no db access), but without an actual Attribute generated,
                 one cannot access it via .db, the AttributeHandler or see it with `examine`.
+        Example:
+        ::
+
+            class Character(DefaultCharacter):
+                foo = AttributeProperty(default="Bar")
 
         """
         self._default = default