From ab8fd60946ac2b8fe194170e3c3a7fec26a037d4 Mon Sep 17 00:00:00 2001 From: Trysha-rbrn Date: Sun, 7 Jun 2026 19:52:05 +0200 Subject: [PATCH 1/2] Add DB_Open and DB_Close documentation --- frontend/docs/scripting/functions/DB_Close.md | 95 ++++++++++++++++++ frontend/docs/scripting/functions/DB_Open.md | 98 +++++++++++++++++++ 2 files changed, 193 insertions(+) create mode 100644 frontend/docs/scripting/functions/DB_Close.md create mode 100644 frontend/docs/scripting/functions/DB_Open.md diff --git a/frontend/docs/scripting/functions/DB_Close.md b/frontend/docs/scripting/functions/DB_Close.md new file mode 100644 index 00000000000..063afb65aa9 --- /dev/null +++ b/frontend/docs/scripting/functions/DB_Close.md @@ -0,0 +1,95 @@ +--- +title: DB_Close +sidebar_label: DB_Close +description: Closes a SQLite database connection that was opened with `DB_Open`. +tags: ["sqlite"] +--- + +## Description + +Closes a SQLite database connection that was opened with [DB_Open](DB_Open). + +| Name | Description | +| ----- | -------------------------------------------------------------------------------- | +| DB:db | The handle of the database connection to close (returned by [DB_Open](DB_Open)). | + +## Returns + +**true** - The function executed successfully. + +**false** - The function failed to execute. This could mean that the database connection handle is invalid. + +## Examples + +```c +static DB:gDBConnectionHandle; + +// ... + +public OnGameModeInit() +{ + // ... + + // Create a connection to a database + gDBConnectionHandle = DB_Open("example.db"); + + // If connection to the database exists + if (gDBConnectionHandle) + { + // Successfully created a connection to the database + print("Successfully created a connection to database \"example.db\"."); + } + else + { + // Failed to create a connection to the database + print("Failed to open a connection to database \"example.db\"."); + } + + // ... + + return 1; +} + +public OnGameModeExit() +{ + // Close the connection to the database if connection is open + if (DB_Close(gDBConnectionHandle)) + { + // Extra cleanup + gDBConnectionHandle = DB:0; + } + + // ... + + return 1; +} +``` + +## Notes + +:::warning + +Using an invalid handle other than zero will crash your server! Get a valid database connection handle by using [DB_Open](DB_Open). + +::: + +## Related Functions + +- [DB_Open](DB_Open): Open a connection to an SQLite database +- [DB_Close](DB_Close): Close the connection to an SQLite database +- [DB_ExecuteQuery](DB_ExecuteQuery): Query an SQLite database +- [DB_FreeResultSet](DB_FreeResultSet): Free result memory from a DB_ExecuteQuery +- [DB_GetRowCount](DB_GetRowCount): Get the number of rows in a result +- [DB_SelectNextRow](DB_SelectNextRow): Move to the next row +- [DB_GetFieldCount](DB_GetFieldCount): Get the number of fields in a result +- [DB_GetFieldName](DB_GetFieldName): Returns the name of a field at a particular index +- [DB_GetFieldString](DB_GetFieldString): Get content of field with specified ID from current result row +- [DB_GetFieldStringByName](DB_GetFieldStringByName): Get content of field with specified name from current result row +- [DB_GetFieldInt](DB_GetFieldInt): Get content of field as an integer with specified ID from current result row +- [DB_GetFieldIntByName](DB_GetFieldIntByName): Get content of field as an integer with specified name from current result row +- [DB_GetFieldFloat](DB_GetFieldFloat): Get content of field as a float with specified ID from current result row +- [DB_GetFieldFloatByName](DB_GetFieldFloatByName): Get content of field as a float with specified name from current result row +- [DB_GetMemHandle](DB_GetMemHandle): Get memory handle for an SQLite database that was opened with DB_Open. +- [DB_GetLegacyDBResult](DB_GetLegacyDBResult): Get memory handle for an SQLite query that was executed with DB_ExecuteQuery. +- [DB_GetDatabaseConnectionCount](DB_GetDatabaseConnectionCount): The function gets the number of open database connections for debugging purposes. +- [DB_GetDatabaseResultSetCount](DB_GetDatabaseResultSetCount): The function gets the number of open database results. diff --git a/frontend/docs/scripting/functions/DB_Open.md b/frontend/docs/scripting/functions/DB_Open.md new file mode 100644 index 00000000000..6f6440195a3 --- /dev/null +++ b/frontend/docs/scripting/functions/DB_Open.md @@ -0,0 +1,98 @@ +--- +title: DB_Open +sidebar_label: DB_Open +description: The function is used to open a connection to a SQLite database file, which is inside the `/scriptfiles` folder. +tags: ["sqlite"] +--- + +## Description + +The function is used to open a connection to a SQLite database, which is inside the "/scriptfiles" folder. + +| Name | Description | +| ------------------------------------------------------------------- | ----------------------------------------------------- | +| const name[] | File name of the database | +| SQLITE_OPEN:flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | [Permissions / Flags](../resources/sqlite-open-flags) | + +## Returns + +Returns index (starting at 1) of the database connection. + +## Examples + +```c +static DB:gDBConnectionHandle; + +// ... + +public OnGameModeInit() +{ + // ... + + // Create a connection to a database + gDBConnectionHandle = DB_Open("example.db"); + + // If connection to the database exists + if (gDBConnectionHandle) + { + // Successfully created a connection to the database + print("Successfully created a connection to database \"example.db\"."); + } + else + { + // Failed to create a connection to the database + print("Failed to open a connection to database \"example.db\"."); + } + + // ... + + return 1; +} + +public OnGameModeExit() +{ + // Close the connection to the database if connection is open + if (DB_Close(gDBConnectionHandle)) + { + // Extra cleanup + gDBConnectionHandle = DB:0; + } + + // ... + + return 1; +} +``` + +## Notes + +:::warning + +It will create a new SQLite database file, if there is no SQLite database file with the same file name available. Close your SQLite database connection with [DB_Close](DB_Close)! + +::: + +## Related Functions + +- [DB_Open](DB_Open): Open a connection to an SQLite database +- [DB_Close](DB_Close): Close the connection to an SQLite database +- [DB_ExecuteQuery](DB_ExecuteQuery): Query an SQLite database +- [DB_FreeResultSet](DB_FreeResultSet): Free result memory from a DB_ExecuteQuery +- [DB_GetRowCount](DB_GetRowCount): Get the number of rows in a result +- [DB_SelectNextRow](DB_SelectNextRow): Move to the next row +- [DB_GetFieldCount](DB_GetFieldCount): Get the number of fields in a result +- [DB_GetFieldName](DB_GetFieldName): Returns the name of a field at a particular index +- [DB_GetFieldString](DB_GetFieldString): Get content of field with specified ID from current result row +- [DB_GetFieldStringByName](DB_GetFieldStringByName): Get content of field with specified name from current result row +- [DB_GetFieldInt](DB_GetFieldInt): Get content of field as an integer with specified ID from current result row +- [DB_GetFieldIntByName](DB_GetFieldIntByName): Get content of field as an integer with specified name from current result row +- [DB_GetFieldFloat](DB_GetFieldFloat): Get content of field as a float with specified ID from current result row +- [DB_GetFieldFloatByName](DB_GetFieldFloatByName): Get content of field as a float with specified name from current result row +- [DB_GetMemHandle](DB_GetMemHandle): Get memory handle for an SQLite database that was opened with DB_Open. +- [DB_GetLegacyDBResult](DB_GetLegacyDBResult): Get memory handle for an SQLite query that was executed with DB_ExecuteQuery. +- [DB_GetDatabaseConnectionCount](DB_GetDatabaseConnectionCount): The function gets the number of open database connections for debugging purposes. +- [DB_GetDatabaseResultSetCount](DB_GetDatabaseResultSetCount): The function gets the number of open database results. + +## Related Resources + +- [SQLite Open Flags](../resources/sqlite-open-flags) From 32a361c18e62d4ea0fc1bfe0fc61bff6f36a93e9 Mon Sep 17 00:00:00 2001 From: Trysha-rbrn Date: Sun, 7 Jun 2026 20:06:28 +0200 Subject: [PATCH 2/2] docs: add contributor guide for documentation source --- README.md | 2 +- frontend/README.md | 65 +++++++++++++++++++++++++++++++++++++++------- 2 files changed, 56 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index f79fafe60df..ad770a0a942 100644 --- a/README.md +++ b/README.md @@ -36,7 +36,7 @@ This monorepo contains the web services and documentation for open.mp and SA-MP. ## Overview - `frontend/docs/` Wiki documentation for SA-MP and open.mp in Markdown format. Translations at `frontend/i18n/`. -- `frontend/` [Next.js](https://nextjs.org) app for the https://open.mp site. +- `frontend/` [Docusaurus](https://docusaurus.io/) site for https://open.mp and its documentation. See [frontend/README.md](frontend/README.md) for a guide on contributing to the docs. - `prisma/` [Prisma](https://prisma.io/) database models for generating Go code and SQL migrations. - `app/` Backend API for server listings, accounts, etc. diff --git a/frontend/README.md b/frontend/README.md index 76cfdf2a592..4620fb955e7 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -1,28 +1,73 @@ # Website -This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. +This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. It serves as the primary documentation and wiki for open.mp and SA-MP. + +## Documentation Structure + +- **Docs Source:** All documentation pages are located in `docs/`. They are written in Markdown (`.md`) or MDX (`.mdx`). +- **Translations:** Localized content is stored in `i18n/`. Each language has its own subdirectory (e.g., `i18n/es/` for Spanish). +- **Static Assets:** Images and other static files used in docs are in `static/images/`. + +## Contributing to Documentation + +We welcome contributions to our documentation! Whether you're fixing a typo or adding a new guide, your help is appreciated. + +### Local Development + +To preview your changes locally: + +1. **Navigate to the frontend directory:** + ```bash + cd frontend + ``` +2. **Install dependencies:** + ```bash + npm install + ``` +3. **Start the development server:** + ```bash + npm start + ``` + The site will be available at `http://localhost:3000`. Most changes to Markdown files will live-reload in the browser. + +### Adding or Editing Pages + +- To **edit** an existing page, find the corresponding `.md` file in `docs/` and make your changes. +- To **add** a new page, create a new `.md` file in the appropriate subdirectory of `docs/`. +- Remember to update the **metadata** (front matter) at the top of the file: + ```markdown + --- + title: Page Title + sidebar_label: Sidebar Label + description: Brief description of the page. + --- + ``` + +### Workflow + +For a detailed guide on our documentation standards and the "Edit this page" workflow, please refer to the [Contributing Guide](docs/meta/Contributing.md). + +## Project Commands ### Installation -``` -$ npm i +```bash +npm i ``` ### Local Development -``` -$ npm start +```bash +npm start ``` -This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. - ### Build -``` -$ npm run build +```bash +npm run build ``` -This command generates static content into the `build` directory and can be served using any static contents hosting service. +This command generates static content into the `build` directory. ### Deployment