Docs: world api general cleanup/overhaul (#2598)

* Docs: world api general cleanup/overhaul

* add pep-0287 to style doc

* some cleanup, reorganization, and grammar improvements

* reorder item and region creation

* address review comments

* fix indent

* linter grammar

Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com>

---------

Co-authored-by: Exempt-Medic <60412657+Exempt-Medic@users.noreply.github.com>

docs/options api.md

@@ -27,14 +27,15 @@ Choice, and defining `alias_true = option_full`.
 - All options support `random` as a generic option. `random` chooses from any of the available values for that option,
 and is reserved by AP. You can set this as your default value, but you cannot define your own `option_random`.
 
-As an example, suppose we want an option that lets the user start their game with a sword in their inventory. Let's
-create our option class (with a docstring), give it a `display_name`, and add it to our game's options dataclass:
+As an example, suppose we want an option that lets the user start their game with a sword in their inventory, an option
+to let the player choose the difficulty, and an option to choose how much health the final boss has. Let's create our
+option classes (with a docstring), give them a `display_name`, and add them to our game's options dataclass:
 
 ```python
 # options.py
 from dataclasses import dataclass
 
-from Options import Toggle, PerGameCommonOptions
+from Options import Toggle, Range, Choice, PerGameCommonOptions
 
 
 class StartingSword(Toggle):
@@ -42,13 +43,33 @@ class StartingSword(Toggle):
     display_name = "Start With Sword"
 
 
+class Difficulty(Choice):
+    """Sets overall game difficulty."""
+    display_name = "Difficulty"
+    option_easy = 0
+    option_normal = 1
+    option_hard = 2
+    alias_beginner = 0  # same as easy but allows the player to use beginner as an alternative for easy in the result in their options
+    alias_expert = 2  # same as hard
+    default = 1  # default to normal
+
+
+class FinalBossHP(Range):
+    """Sets the HP of the final boss"""
+    display_name = "Final Boss HP"
+    range_start = 100
+    range_end = 10000
+    default = 2000
+
+
 @dataclass
 class ExampleGameOptions(PerGameCommonOptions):
     starting_sword: StartingSword
+    difficulty: Difficulty
+    final_boss_health: FinalBossHP
 ```
 
-This will create a `Toggle` option, internally called `starting_sword`. To then submit this to the multiworld, we add it
-to our world's `__init__.py`:
+To then submit this to the multiworld, we add it to our world's `__init__.py`:
 
 ```python
 from worlds.AutoWorld import World