Merge branch 'docs' into main

docs/how-to-guides.md

@@ -0,0 +1,11 @@
+# How-to Guides
+
+## Libretro API
+
+The most important reference is the [`libretro.h`](https://github.com/libretro/libretro-common/blob/master/include/libretro.h) file. It contains all information about the workings and expectations of the API.It can be found on the official repository of libretro and open-source cores.
+
+When ported into the Python wrapper, every objects name can deviate from the C name, but the original name should be preserved in the objects docstring.
+
+## Custom frontend
+
+Custom frontends can be created by inhereting the `RetroPy` class.

docs/index.md

@@ -1,3 +1,9 @@
 # Home
 
 ## Welcome to retropy's documentation
+
+**THIS DOCUMENTATION IS A WORK IN PROGRESS.**
+
+**EXAMPLES AND EXPLANATIONS ARE EITHER ABSENT OR DO NOT ALIGN WITH THE ACTUAL CODE.**
+
+https://www.markdownguide.org/basic-syntax/

docs/installation.md

@@ -0,0 +1,32 @@
+# Installation
+
+## pip
+
+```
+pip install retropy
+```
+
+By default, retropy does not have any external dependencies. However, some additional features are accessable if other packages are available[^1].
+
+``` bash
+pip install retropy[numpy]  # retropy + numpy
+pip install retropy[gym]    # retropy + numpy + gymnasium
+pip install retropy[pygame] # retropy + numpy + pygame
+pip install retropy[pyglet] # retropy + numpy + pyglet
+pip install retropy[dev]    # retropy + numpy + black + mkdocs
+```
+
+## Releases
+
+Download wanted version from [Releases](https://github.com/29th-Day/retropy/releases "GitHub Releases"). Extract to local or path-accessable folder.
+
+## Nightly Version
+
+1. Clone current version from repo
+```
+git clone https://github.com/29th-Day/retropy.git
+```
+
+2. Move `src/retropy` to local or path-accessable folder
+
+[^1]: `ModuleNotFoundError` will be raised if unavailable feature is called

docs/tutorials/customization.md

@@ -0,0 +1,8 @@
+# Customization
+
+retropy is designed to be extensible. This is done by inheriting the `RetroPy` class.
+
+``` py
+class MyCustomRetroPy(RetroPy):
+    ...
+```

docs/tutorials/frontends.md

@@ -0,0 +1,60 @@
+# Frontends
+
+
+## Gymnasium
+
+Frontend implementing `gymnasium`'s API (formerly `gym`).
+
+Particularly useful for AI applications, especially in reinforcement learning. Additional details can be found in the [documentation](https://gymnasium.farama.org/ "Gymnasium Documentation").
+
+``` py
+
+from retropy.frontends import RetroPyGym
+
+env = RetroPyGym(dll_path)
+
+terminated, truncated = False, False
+obs, info = env.reset()
+
+while not terminated and not truncated:
+    action = ...
+
+    obs, reward, terminated, truncated, info = env.step(action)
+
+env.close()
+
+```
+
+## Interactive
+
+If your primary goal is to play retro games, I strongly recommend using player-focused frontends like [RetroArch](https://www.retroarch.com/). Interactive frontends within retropy are implemented to showcase its capabilities and for debugging purposes.
+
+### Pygame
+
+Frontend using pygame. No audio support due to the way pygame handles audio.
+
+``` py
+from retropy.frontends import RetroPyGame
+
+core = RetroPyGame(dll_path)
+
+core.load(rom_path)
+
+core.run()
+
+```
+
+### Pyglet
+
+Frontend using pygame. Maybe audio support?
+
+``` py
+from retropy.frontends import RetroPyGlet
+
+core = RetroPyGlet(dll_path)
+
+core.load(rom_path)
+
+core.run()
+
+```

docs/tutorials/getting-started.md

@@ -0,0 +1,81 @@
+# Getting started
+
+<!--
+## Basics
+
+``` py
+from retropy import RetroPy
+
+core = RetroPy(dll_path)         # load core
+
+core.load(rom_path)              # load game
+
+for _ in range(1):
+    frame = core.frame_advance() # run emulator for one frame
+```
+-->
+
+## Load core
+
+``` py
+from retropy import RetroPy
+```
+
+## Load game
+
+...
+
+## Run core
+
+## Input
+
+``` py
+
+from retropy import Device, Joypad, Analog
+
+...
+
+player = 0
+core.controller[player].set_state(Device.JOYPAD, 0, Joypad.A, 1)
+core.controller[player].set_state(Device.ANALOG, Analog.LEFT_STICK, Analog.X, 0x9FFF)
+
+```
+
+## Savestates
+
+``` py
+from retropy.utils.savestate import Savestate
+
+...
+
+save = core.save_state()            # create a savestate
+
+save.write("./save.svt")            # write savestate to file
+
+core.reset()                        # reset core
+
+del save                            # delete savestate for demonstrational purposes
+
+save = Savestate().load("save.svt") # load savestate from file
+
+core.load_state(save)               # load previous savestate
+
+```
+## Complete code
+
+``` py
+from retropy import RetroPy
+
+core = RetroPy(dll_path)
+
+core_info = core.system_info()
+
+core.load(rom_path)
+
+game_info = core.system_av_info()
+
+for _ in range(1):
+    frame = core.frame_advance()
+
+
+```

docs/tutorials/index.md

@@ -0,0 +1,10 @@
+# Tutorials
+
+This section is intendet to get the user going with retropy.
+
+Throughout this section, the two variables are assumned to be present and valid.
+
+``` py
+dll_path = "path/to/core.*" # path to libretro core
+rom_path = "path/to/rom.*"  # path to valid rom
+```

mkdocs.yml

@@ -2,7 +2,37 @@ site_name: retropy's Documentation
 site_url: https://29th-Day.github.io/retropy/
 repo_url: https://github.com/29th-Day/retropy
 repo_name: 29th-Day/retropy
+
+nav:
+  - index.md
+  - installation.md
+  # - tutorials.md
+  - Tutorials:
+      - tutorials/index.md
+      - tutorials/getting-started.md
+      - tutorials/frontends.md
+      - tutorials/customization.md
+  - how-to-guides.md
+  - Code Reference: reference/
+  - mkdocs.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      default_handler: python
+      handlers:
+        python:
+          paths: [src]
+  - gen-files:
+      scripts:
+      - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - section-index
+
 theme:
+  favicon: img/favicon.ico
+  logo: img/logo.png
   name: material
   features:
     - navigation.tabs
@@ -12,7 +42,7 @@ theme:
     - search.suggest
     - search.highlight
     - content.tabs.link
-    - content.code.annotation
+    - content.code.annotate
     - content.code.copy
   language: en
   palette:
@@ -28,7 +58,7 @@ theme:
       toggle:
         icon: material/weather-night
         name: Switch to system mode
-      primary: teal
+      primary: purple
       accent: lime
 
     # Palette toggle for light mode
@@ -37,12 +67,8 @@ theme:
       toggle:
         icon: material/weather-sunny
         name: Switch to dark mode
-      primary: teal
-      accent: purple
-
-
-# plugins:
-#   - social
+      primary: purple
+      accent: teal
 
 extra:
   social:
@@ -64,9 +90,6 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.mark
   - attr_list
-  - pymdownx.emoji:
-      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
 
 copyright: |
   &copy; 2023 <a href="https://github.com/29th-Day" target="_blank" rel="noopener">29th-Day</a>