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
+As an example, suppose we want an option that lets the user start their game with a sword in their inventory, an option
-create our option class (with a docstring), give it a `display_name`, and add it to our game's options dataclass:
+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 then submit this to the multiworld, we add it to our world's `__init__.py`:
-to our world's `__init__.py`:
 
 ```python
 from worlds.AutoWorld import World

docs/style.md

@@ -6,7 +6,6 @@
 * 120 character per line for all source files.
 * Avoid white space errors like trailing spaces.
 
-
 ## Python Code
 
 * We mostly follow [PEP8](https://peps.python.org/pep-0008/). Read below to see the differences.
@@ -18,9 +17,10 @@
 * Use type annotations where possible for function signatures and class members.
 * Use type annotations where appropriate for local variables (e.g. `var: List[int] = []`, or when the
   type is hard or impossible to deduce.) Clear annotations help developers look up and validate API calls.
+* New classes, attributes, and methods in core code should have docstrings that follow
+  [reST style](https://peps.python.org/pep-0287/).
 * Worlds that do not follow PEP8 should still have a consistent style across its files to make reading easier.
 
-
 ## Markdown
 
 * We almost follow [Google's styleguide](https://google.github.io/styleguide/docguide/style.html).
@@ -30,20 +30,17 @@
 * One space between bullet/number and text.
 * No lazy numbering.
 
-
 ## HTML
 
 * Indent with 2 spaces for new code.
 * kebab-case for ids and classes.
 
-
 ## CSS
 
 * Indent with 2 spaces for new code.
 * `{` on the same line as the selector.
 * No space between selector and `{`.
 
-
 ## JS
 
 * Indent with 2 spaces.