Merge pull request #51 from rommapp/mega-docs-cleanup

Mega docs cleanup

Author: gantoine

.github/resources/social-preview.svg

@@ -0,0 +1,165 @@
+# API Reference
+
+RomM provides a comprehensive REST API that allows you to programmatically interact with your RomM instance. Most API endpoints are authenticated and follow RESTful conventions.
+
+## Interactive Documentation
+
+RomM automatically generates interactive API documentation using OpenAPI (Swagger). You can access the interactive API docs directly from your running instance:
+
+- **Swagger UI**: Available at `http://your-instance:3000/api/docs`
+- **ReDoc**: Available at `http://your-instance:3000/api/redoc`
+
+These interactive docs allow you to:
+
+- Browse all available endpoints
+- View request/response schemas
+- Test API calls directly from your browser
+- Understand authentication requirements
+- Download the OpenAPI specification
+
+## Base URL
+
+The API base URL is typically:
+
+```text
+http://your-instance:3000/api
+```
+
+Replace `your-instance` with your actual RomM instance URL or IP address.
+
+## Authentication
+
+All API endpoints require authentication. RomM supports:
+
+- **Basic HTTP Authentication** - Username and password
+- **OAuth2 Password Bearer** - Token-based authentication (recommended for API usage)
+
+When using OAuth2, you'll need to obtain a token from `/api/token` endpoint and include it in the `Authorization` header as `Bearer <token>`.
+
+### OAuth2 Scopes
+
+The API uses OAuth2 scopes to control access to different resources:
+
+**Read Scopes:**
+
+- `me.read` - View your profile
+- `roms.read` - View ROMs
+- `platforms.read` - View platforms
+- `assets.read` - View assets
+- `firmware.read` - View firmware
+- `roms.user.read` - View user-rom properties
+- `collections.read` - View collections
+- `users.read` - View users
+
+**Write Scopes:**
+
+- `me.write` - Modify your profile
+- `assets.write` - Modify assets
+- `roms.user.write` - Modify user-rom properties
+- `collections.write` - Modify collections
+- `roms.write` - Modify ROMs
+- `platforms.write` - Modify platforms
+- `firmware.write` - Modify firmware
+- `users.write` - Modify users
+- `tasks.run` - Run tasks
+
+## API Endpoints Overview
+
+The RomM API provides comprehensive endpoints for managing all aspects of your ROM collection:
+
+### Core Resources
+
+- **Platforms** - Manage and configure gaming platforms
+- **ROMs** - Full CRUD operations for ROM files with extensive filtering, searching, and metadata matching
+- **Collections** - Create and manage ROM collections, smart collections, and virtual collections
+- **Users** - User management, authentication, invite links, and profiles
+
+### Supporting Features
+
+- **Authentication** - OAuth2 token management, OIDC login, password resets
+- **Search** - Metadata provider search for ROMs and covers
+- **Tasks** - Background task management and execution
+- **Assets** - Save files, states, screenshots management
+- **Firmware** - Upload and manage firmware files for emulation
+- **Configuration** - System configuration, platform bindings, and exclusions
+- **Feeds** - Integration feeds for WebRcade and Tinfoil
+- **Statistics** - System statistics and resource tracking
+
+For complete endpoint documentation including request/response schemas, query parameters, and authentication requirements, visit the interactive API documentation at `/api/docs` or `/api/redoc` on your RomM instance.
+
+## Example Usage
+
+### Using cURL
+
+```bash
+# Get all libraries
+curl -u username:password http://your-instance:3000/api/libraries
+
+# Get a specific ROM
+curl -u username:password http://your-instance:3000/api/roms/123
+
+# Create a new ROM entry
+curl -X POST -u username:password \
+  -H "Content-Type: application/json" \
+  -d '{"name": "New ROM", "platform_id": 1}' \
+  http://your-instance:3000/api/roms
+```
+
+### Using Python
+
+```python
+import requests
+from requests.auth import HTTPBasicAuth
+
+# Setup authentication
+auth = HTTPBasicAuth('username', 'password')
+base_url = 'http://your-instance:3000/api'
+
+# Get all libraries
+response = requests.get(f'{base_url}/libraries', auth=auth)
+libraries = response.json()
+
+# Get a specific ROM
+response = requests.get(f'{base_url}/roms/123', auth=auth)
+rom = response.json()
+```
+
+### Using JavaScript/Node.js
+
+```javascript
+const axios = require("axios");
+
+// Setup authentication
+const api = axios.create({
+    baseURL: "http://your-instance:3000/api",
+    auth: {
+        username: "username",
+        password: "password",
+    },
+});
+
+// Get all libraries
+const libraries = await api.get("/libraries");
+
+// Get a specific ROM
+const rom = await api.get("/roms/123");
+```
+
+## OpenAPI Specification
+
+You can download the complete OpenAPI specification from your RomM instance:
+
+```text
+http://your-instance:3000/api/openapi.json
+```
+
+This specification can be imported into API testing tools like Postman, used to generate client libraries, or used for API mocking.
+
+## Getting Help
+
+For API-specific questions or issues:
+
+1. Check the interactive documentation at `/api/docs` or `/api/redoc` on your instance
+2. Review the code in the [RomM repository](https://github.com/rommapp/romm)
+3. Open an issue on [GitHub](https://github.com/rommapp/romm/issues)
+4. Join the [Discord community](https://discord.com/invite/romm)

docs/API-and-Development/API-Reference.md

@@ -0,0 +1,81 @@
+# Contributing to RomM
+
+Thank you for considering contributing to RomM! This document outlines some guidelines to help you get started with your contributions.
+
+**If you're looking to implement a large feature or make significant changes to the project, it's best to open an issue first AND join the Discord to discuss your ideas with the maintainers.**
+
+## Code of Conduct
+
+Please note that this project adheres to the Contributor Covenant [code of conduct](CODE_OF_CONDUCT.md). By participating in this project, you are expected to uphold this code.
+
+## AI Assistance Notice
+
+> [!IMPORTANT]
+>
+> If you are using **any kind of AI assistance** to contribute to RomM, it must be disclosed in the pull request.
+
+If you are using any kind of AI assistance while contributing to RomM **this must be disclosed in the pull request**, along with the extent to which AI assistance was used (e.g. docs only vs. code generation). If PR responses are being generated by an AI, disclose that as well. As a small exception, trivial tab-completion doesn't need to be disclosed.
+
+An example disclosure:
+
+> This PR was written primarily by Claude Code.
+
+Or a more detailed disclosure:
+
+> I consulted ChatGPT to understand the codebase but the solution
+> was fully authored manually by myself.
+
+Failure to disclose this is rude to the human operators on the other end of the pull request, but it also makes it difficult to determine how much scrutiny to apply to the contribution.
+
+In a perfect world, AI assistance would produce equal or higher quality work than any human. That isn't the world we live in today, and in most cases it's generating slop.
+
+Please be respectful to maintainers and disclose AI assistance.
+
+## Contributing to the Docs
+
+If you would like to contribute to the project's [documentation](https://docs.romm.app), open a pull request against [the docs repo](https://github.com/rommapp/docs). We welcome any contributions that help improve the documentation (new pages, updates, or corrections).
+
+## Adding Translations
+
+If you would like to translate the project into another language, create a new folder under the `frontend/src/locales` directory, and follow the existing language files as a template. Once you've created the new language file, open a pull request to add it to the project.
+
+## How to Contribute Code
+
+1. Fork the repository.
+2. Clone your forked repository: `git clone https://github.com/your-username/romm.git`
+3. Checkout the `master` branch: `git checkout master`
+4. Follow the steps in the [developer setup guide](DEVELOPER_SETUP.md)
+5. Create a new branch for your feature/fix: `git checkout -b feature-or-fix-name`
+6. Make your changes and commit them with descriptive commit messages: `git commit -am 'Add feature XYZ'`
+7. Push your changes to your fork: `git push origin feature-or-fix-name`
+8. Open a pull request to the `master` branch of the original repository.
+
+## Pull Request Guidelines
+
+- Make sure your code follows the project's coding standards.
+- Test your changes locally before opening a pull request.
+- Update the documentation if necessary.
+- Ensure all existing tests pass, and add new tests for new functionality.
+- Use clear and descriptive titles and descriptions for your pull requests.
+
+## Code Style
+
+Follow the existing code style used throughout the project. If working with VSCode or a similar editor, consider installing these extensions:
+
+- [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
+- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)
+- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)
+- [Ruff](https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff)
+- [Vue - Official](https://marketplace.visualstudio.com/items?itemName=Vue.volar)
+
+## Issue Reporting
+
+If you encounter any bugs or have suggestions for improvements, please [create an issue](https://github.com/rommapp/romm/issues) on GitHub. Provide as much detail as possible, including steps to reproduce the issue if applicable.
+
+## Licensing
+
+By contributing to RomM, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE).
+
+---
+
+Thank you for contributing to RomM! Your help is greatly appreciated.

docs/API-and-Development/Contributing.md

@@ -0,0 +1,41 @@
+# Setting up RomM for development
+
+Docker provides a quick and easy way to get started with RomM by encapsulating all dependencies within Docker containers. This guide will walk you through the process of setting up RomM for development using Docker.
+
+## Environment setup
+
+### Create the mock structure with at least one rom and empty config for manual testing
+
+```sh
+mkdir -p romm_mock/library/roms/switch
+touch romm_mock/library/roms/switch/metroid.xci
+mkdir -p romm_mock/resources
+mkdir -p romm_mock/assets
+mkdir -p romm_mock/config
+touch romm_mock/config/config.yml
+```
+
+### Copy env.template to .env and fill the variables
+
+```sh
+cp env.template .env
+```
+
+```dotenv
+ROMM_BASE_PATH=/app/romm
+DEV_MODE=true
+```
+
+### Build the image
+
+```sh
+docker compose build  # or `docker compose build --no-cache` to rebuild from scratch
+```
+
+### Spin up the Docker containers
+
+```sh
+docker compose up -d
+```
+
+And you're done! You can access the app at `http://localhost:3000`. Any changes made to the code will be automatically reflected in the app thanks to the volume mounts.

docs/API-and-Development/Development-Setup.md

@@ -0,0 +1,14 @@
+---
+search:
+    exclude: true
+---
+
+# API & Development
+
+Welcome to the RomM API & Development documentation. This section contains resources for developers looking to interact with RomM programmatically or contribute to its development.
+
+## Contents
+
+- **[API Reference](API-Reference.md)** - Complete API documentation with endpoints, schemas, and examples
+- **[Contributing](Contributing.md)** - Guidelines for contributing code, translations, and documentation
+- **[Development Setup](Development-Setup.md)** - How to set up your development environment

docs/API-and-Development/index.md

@@ -10,7 +10,7 @@ You'll want to set the following environment variable before starting RomM:
 
 ### Sessions
 
-When the `/login` endpoint is called with valid credentials, a `session_id` is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Redis (or in-memory if Redis is disabled) which maps the token to the user. This way no sensitive information is stored on the client.
+When the `/login` endpoint is called with valid credentials, a `session_id` is generated, stored as a cookie and sent to the browser. The same token is used to create a cache entry in Valkey (or in-memory if Valkey is disabled) which maps the token to the user. This way no sensitive information is stored on the client.
 
 ### Roles