first-pass API docs

docs/reference/ability.md

@@ -0,0 +1 @@
+::: osrlib.ability

docs/reference/adventure.md

@@ -0,0 +1 @@
+::: osrlib.adventure

docs/reference/character_classes.md

@@ -0,0 +1,12 @@
+::: osrlib.character_classes
+::: osrlib.character_classes.all_character_classes
+::: osrlib.character_classes.class_levels
+<!--
+::: osrlib.character_classes.cleric_levels
+::: osrlib.character_classes.elf_levels
+::: osrlib.character_classes.fighter_levels
+::: osrlib.character_classes.magic_user_levels
+::: osrlib.character_classes.thief_levels
+::: osrlib.character_classes.dwarf_levels
+::: osrlib.character_classes.halfling_levels
+-->

docs/reference/constants.md

@@ -0,0 +1,8 @@
+::: osrlib.constants
+::: osrlib.constants.CLERIC_NAMES
+::: osrlib.constants.DWARF_NAMES
+::: osrlib.constants.ELF_NAMES
+::: osrlib.constants.FIGHTER_NAMES
+::: osrlib.constants.HALFLING_NAMES
+::: osrlib.constants.MAGIC_USER_NAMES
+::: osrlib.constants.THIEF_NAMES

docs/reference/dungeon.md

@@ -0,0 +1 @@
+::: osrlib.dungeon

docs/reference/dungeon_master.md

@@ -0,0 +1 @@
+::: osrlib.dungeon_master

docs/reference/encounter.md

@@ -0,0 +1 @@
+::: osrlib.encounter

docs/reference/enums.md

@@ -0,0 +1 @@
+::: osrlib.enums

docs/reference/game_manager.md

@@ -0,0 +1 @@
+::: osrlib.game_manager

docs/reference/inventory.md

@@ -0,0 +1 @@
+::: osrlib.inventory

docs/reference/item.md

@@ -0,0 +1 @@
+::: osrlib.item

docs/reference/item_factories.md

@@ -0,0 +1 @@
+::: osrlib.item_factories

docs/reference/monster.md

@@ -0,0 +1 @@
+::: osrlib.monster

docs/reference/monster_manual.md

@@ -0,0 +1 @@
+::: osrlib.monster_manual

docs/reference/party.md

@@ -0,0 +1 @@
+::: osrlib.party

docs/reference/player_character.md

@@ -0,0 +1 @@
+::: osrlib.player_character

docs/reference/quest.md

@@ -0,0 +1 @@
+::: osrlib.quest

docs/reference/saving_throws.md

@@ -0,0 +1 @@
+::: osrlib.saving_throws

docs/reference/treasure.md

@@ -0,0 +1 @@
+::: osrlib.treasure

docs/reference/utils.md

@@ -0,0 +1 @@
+::: osrlib.utils

mkdocs.yml

@@ -4,6 +4,9 @@ site_description: Adventures in turn-based text
 site_url: https://osrapps.github.io/osr-console
 repo_name: osr-console
 repo_url: https://github.com/osrapps/osr-console
+watch:
+  - "docs/"
+  - "osrlib/osrlib/"
 
 theme:
   name: material
@@ -29,18 +32,19 @@ theme:
         name: Switch to light mode
 
   font:
-    text: Sora
+    #text: Sora # BIG!
     #text: PT Sans Caption
-    #text: Actor
+    text: Actor
     #text: Alef
     #text: Palanquin
 
-    code: Martian Mono
+    #code: Martian Mono # BIG!
     #code: JetBrains Mono
     #code: BIZ UDPGothic
     #code: Palanquin Dark
     #code: Oxygen Mono
     #code: IBM Plex Mono
+    code: Chivo Mono
 
   features:
     - navigation.instant
@@ -74,4 +78,30 @@ markdown_extensions:
   - pymdownx.superfences
 
 extra_css:
-  - 'main.css'
+  - "main.css"
+
+plugins:
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [osrlib]
+          import:
+            - https://docs.python.org/3/objects.inv
+          options:
+            docstring_options:
+              ignore_init_summary: true
+            docstring_section_style: list
+            filters: ["!^_"]
+            heading_level: 2
+            inherited_members: false
+            merge_init_into_class: true
+            separate_signature: true
+            show_root_heading: true
+            show_root_full_path: false
+            show_signature_annotations: true
+            show_source: false
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
+            signature_crossrefs: true
+            summary: true
+            unwrap_annotated: true

osrlib/osrlib/ability.py

@@ -124,9 +124,10 @@ class Strength(Ability):
     It primarily influences hand-to-hand combat and opening doors.
 
     Modifiers:
-        TO_HIT (ModifierType.TO_HIT): Modifies melee (hand-to-hand) attack rolls.
-        DAMAGE (ModifierType.DAMAGE): Modifies damage in melee combat.
-        OPEN_DOORS (ModifierType.OPEN_DOORS): Modifies chances of opening stuck doors.
+
+    - TO_HIT (`ModifierType.TO_HIT`): Modifies melee (hand-to-hand) attack rolls.
+    - DAMAGE (`ModifierType.DAMAGE`): Modifies damage in melee combat.
+    - OPEN_DOORS (`ModifierType.OPEN_DOORS`): Modifies chances of opening stuck doors.
     """
 
     def __init__(self, score: int):
@@ -148,9 +149,10 @@ def _init_modifiers(self) -> None:
         """Initialize Strength-specific ability modifiers.
 
         Modifiers:
-            TO_HIT (ModifierType.TO_HIT): Modifies melee (hand-to-hand) attack rolls.
-            DAMAGE (ModifierType.DAMAGE): Modifies damage in melee combat.
-            OPEN_DOORS (ModifierType.OPEN_DOORS): Modifies chances of opening stuck doors.
+
+        - TO_HIT (ModifierType.TO_HIT): Modifies melee (hand-to-hand) attack rolls.
+        - DAMAGE (ModifierType.DAMAGE): Modifies damage in melee combat.
+        - OPEN_DOORS (ModifierType.OPEN_DOORS): Modifies chances of opening stuck doors.
 
         Each modifier is calculated based on the strength score of the character.
         """
@@ -166,7 +168,8 @@ class Intelligence(Ability):
     magical aptitude.
 
     Modifiers:
-        LANGUAGES (ModifierType.LANGUAGES): Modifies the number of additional languages the
+
+    - LANGUAGES (ModifierType.LANGUAGES): Modifies the number of additional languages the
             character can read and write.
     """
 
@@ -197,7 +200,8 @@ def _init_modifiers(self) -> None:
         """Initialize Intelligence-specific ability modifiers.
 
         Modifiers:
-            LANGUAGES (ModifierType.LANGUAGES): Modifies the number of additional languages
+
+        - LANGUAGES (ModifierType.LANGUAGES): Modifies the number of additional languages
             the character can read and write.
 
         The modifier is calculated based on the intelligence score of the character.
@@ -211,7 +215,8 @@ class Wisdom(Ability):
     Wisdom measures a character's common sense, intuition, and willpower.
 
     Modifiers:
-        SAVING_THROWS (ModifierType.SAVING_THROWS): Modifies saving throws against spells and
+
+    - SAVING_THROWS (ModifierType.SAVING_THROWS): Modifies saving throws against spells and
         magical effects.
     """
 
@@ -243,9 +248,10 @@ class Dexterity(Ability):
     Dexterity measures agility, reflexes, and coordination.
 
     Modifiers:
-        TO_HIT (ModifierType.TO_HIT): Modifies ranged attack rolls.
-        AC (ModifierType.AC): Modifies armor class (lower is better).
-        INITIATIVE (ModifierType.INITIATIVE): Modifies initiative rolls.
+
+    - TO_HIT (ModifierType.TO_HIT): Modifies ranged attack rolls.
+    - AC (ModifierType.AC): Modifies armor class (lower is better).
+    - INITIATIVE (ModifierType.INITIATIVE): Modifies initiative rolls.
     """
 
     def __init__(self, score: int):
@@ -286,9 +292,10 @@ def _init_modifiers(self) -> None:
         """Initialize Dexterity-specific ability modifiers.
 
         Modifiers:
-            TO_HIT (ModifierType.TO_HIT): Modifies ranged attack rolls.
-            AC (ModifierType.AC): Modifies armor class (lower is better).
-            INITIATIVE (ModifierType.INITIATIVE): Modifies initiative rolls.
+
+        - TO_HIT (ModifierType.TO_HIT): Modifies ranged attack rolls.
+        - AC (ModifierType.AC): Modifies armor class (lower is better).
+        - INITIATIVE (ModifierType.INITIATIVE): Modifies initiative rolls.
 
         Each modifier is calculated based on the dexterity score of the character.
         """
@@ -303,7 +310,8 @@ class Constitution(Ability):
     Constitution measures stamina, endurance, and overall health.
 
     Modifiers:
-        HP (ModifierType.HP): Modifies hit point (HP) rolls. For example, when initially rolling the
+
+    - HP (ModifierType.HP): Modifies hit point (HP) rolls. For example, when initially rolling the
         character or when the character gains a level.
     """
 
@@ -334,7 +342,8 @@ class Charisma(Ability):
     Charisma measures force of personality, leadership ability, and physical attractiveness.
 
     Modifiers:
-        REACTION (ModifierType.REACTION): Modifies reaction rolls when interacting with NPCs.
+
+    - REACTION (ModifierType.REACTION): Modifies reaction rolls when interacting with NPCs.
     """
 
     def __init__(self, score: int):
@@ -366,7 +375,8 @@ def _init_modifiers(self) -> None:
         """Initialize Charisma-specific ability modifiers.
 
         Modifiers:
-            REACTION (ModifierType.REACTION): Modifies reaction rolls when interacting with NPCs.
+
+        - REACTION (ModifierType.REACTION): Modifies reaction rolls when interacting with NPCs.
 
         The modifier is calculated based on the charisma score of the character.
         """

osrlib/osrlib/adventure.py

@@ -21,11 +21,11 @@ class DungeonAlreadyExistsError(Exception):
 class Adventure:
     """An Adventure is a collection of dungeons that can be played through by a party of characters.
 
-    To start an adventure, add a party to the adventure and then call `start_adventure()`. Once an adventure has started,
-    you can't add or remove the party or its characters until you call `end_adventure()` or the all characters in the
-    party have been killed.
+    To start an adventure, add a ``Party`` to the adventure with ``set_active_party`` and then call ``start_adventure``.
+    Once you've started an adventure, you can't add or remove the party or its characters until you call ``end_adventure``
+    or all the characters in the party have been killed.
 
-    Only one party can play through an adventure at a time.
+    Only one party can play through (be added to) an adventure at a time.
 
     Attributes:
         name (str): The name of the adventure.

osrlib/osrlib/character_classes.py

@@ -106,12 +106,14 @@ def level_up(self, hp_modifier: int = 0) -> bool:
 
         Example:
 
+        ```python
             >>> pc = PlayerCharacter(name="Sckricko", character_class=CharacterClassType.WARRIOR)
             >>> pc.character_class.xp = 2000  # Manually setting XP to meet level-up criteria
             >>> hp_modifier = pc.abilities[AbilityTypes.CONSTITUTION].modifiers[ModifierTypes.HP]
             >>> new_level = pc.character_class.level_up(hp_modifier)
             >>> new_level.level_num
             2
+        ```
 
         Args:
             hp_modifier (int): Hit point bonus or penalty to apply to the HP roll when leveling.