Skip to content

Commit bbee756

Browse files
Trysha-rbrnTrysha-rbrn
authored
docs: add DB_Open/Close and documentation contributor guide (#1256)
* Add DB_Open and DB_Close documentation * docs: add contributor guide for documentation source
1 parent c102926 commit bbee756

4 files changed

Lines changed: 249 additions & 11 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ This monorepo contains the web services and documentation for open.mp and SA-MP.
3636
## Overview
3737

3838
- `frontend/docs/` Wiki documentation for SA-MP and open.mp in Markdown format. Translations at `frontend/i18n/`.
39-
- `frontend/` [Next.js](https://nextjs.org) app for the https://open.mp site.
39+
- `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.
4040
- `prisma/` [Prisma](https://prisma.io/) database models for generating Go code and SQL migrations.
4141
- `app/` Backend API for server listings, accounts, etc.
4242

‎frontend/README.md‎

Lines changed: 55 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,73 @@
11
# Website
22

3-
This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
3+
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.
4+
5+
## Documentation Structure
6+
7+
- **Docs Source:** All documentation pages are located in `docs/`. They are written in Markdown (`.md`) or MDX (`.mdx`).
8+
- **Translations:** Localized content is stored in `i18n/`. Each language has its own subdirectory (e.g., `i18n/es/` for Spanish).
9+
- **Static Assets:** Images and other static files used in docs are in `static/images/`.
10+
11+
## Contributing to Documentation
12+
13+
We welcome contributions to our documentation! Whether you're fixing a typo or adding a new guide, your help is appreciated.
14+
15+
### Local Development
16+
17+
To preview your changes locally:
18+
19+
1. **Navigate to the frontend directory:**
20+
```bash
21+
cd frontend
22+
```
23+
2. **Install dependencies:**
24+
```bash
25+
npm install
26+
```
27+
3. **Start the development server:**
28+
```bash
29+
npm start
30+
```
31+
The site will be available at `http://localhost:3000`. Most changes to Markdown files will live-reload in the browser.
32+
33+
### Adding or Editing Pages
34+
35+
- To **edit** an existing page, find the corresponding `.md` file in `docs/` and make your changes.
36+
- To **add** a new page, create a new `.md` file in the appropriate subdirectory of `docs/`.
37+
- Remember to update the **metadata** (front matter) at the top of the file:
38+
```markdown
39+
---
40+
title: Page Title
41+
sidebar_label: Sidebar Label
42+
description: Brief description of the page.
43+
---
44+
```
45+
46+
### Workflow
47+
48+
For a detailed guide on our documentation standards and the "Edit this page" workflow, please refer to the [Contributing Guide](docs/meta/Contributing.md).
49+
50+
## Project Commands
451

552
### Installation
653

7-
```
8-
$ npm i
54+
```bash
55+
npm i
956
```
1057

1158
### Local Development
1259

13-
```
14-
$ npm start
60+
```bash
61+
npm start
1562
```
1663

17-
This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
18-
1964
### Build
2065

21-
```
22-
$ npm run build
66+
```bash
67+
npm run build
2368
```
2469

25-
This command generates static content into the `build` directory and can be served using any static contents hosting service.
70+
This command generates static content into the `build` directory.
2671

2772
### Deployment
2873

‎frontend/docs/scripting/functions/DB_Close.md‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
1+
---
2+
title: DB_Close
3+
sidebar_label: DB_Close
4+
description: Closes a SQLite database connection that was opened with `DB_Open`.
5+
tags: ["sqlite"]
6+
---
7+
8+
## Description
9+
10+
Closes a SQLite database connection that was opened with [DB_Open](DB_Open).
11+
12+
| Name | Description |
13+
| ----- | -------------------------------------------------------------------------------- |
14+
| DB:db | The handle of the database connection to close (returned by [DB_Open](DB_Open)). |
15+
16+
## Returns
17+
18+
**true** - The function executed successfully.
19+
20+
**false** - The function failed to execute. This could mean that the database connection handle is invalid.
21+
22+
## Examples
23+
24+
```c
25+
static DB:gDBConnectionHandle;
26+
27+
// ...
28+
29+
public OnGameModeInit()
30+
{
31+
// ...
32+
33+
// Create a connection to a database
34+
gDBConnectionHandle = DB_Open("example.db");
35+
36+
// If connection to the database exists
37+
if (gDBConnectionHandle)
38+
{
39+
// Successfully created a connection to the database
40+
print("Successfully created a connection to database \"example.db\".");
41+
}
42+
else
43+
{
44+
// Failed to create a connection to the database
45+
print("Failed to open a connection to database \"example.db\".");
46+
}
47+
48+
// ...
49+
50+
return 1;
51+
}
52+
53+
public OnGameModeExit()
54+
{
55+
// Close the connection to the database if connection is open
56+
if (DB_Close(gDBConnectionHandle))
57+
{
58+
// Extra cleanup
59+
gDBConnectionHandle = DB:0;
60+
}
61+
62+
// ...
63+
64+
return 1;
65+
}
66+
```
67+
68+
## Notes
69+
70+
:::warning
71+
72+
Using an invalid handle other than zero will crash your server! Get a valid database connection handle by using [DB_Open](DB_Open).
73+
74+
:::
75+
76+
## Related Functions
77+
78+
- [DB_Open](DB_Open): Open a connection to an SQLite database
79+
- [DB_Close](DB_Close): Close the connection to an SQLite database
80+
- [DB_ExecuteQuery](DB_ExecuteQuery): Query an SQLite database
81+
- [DB_FreeResultSet](DB_FreeResultSet): Free result memory from a DB_ExecuteQuery
82+
- [DB_GetRowCount](DB_GetRowCount): Get the number of rows in a result
83+
- [DB_SelectNextRow](DB_SelectNextRow): Move to the next row
84+
- [DB_GetFieldCount](DB_GetFieldCount): Get the number of fields in a result
85+
- [DB_GetFieldName](DB_GetFieldName): Returns the name of a field at a particular index
86+
- [DB_GetFieldString](DB_GetFieldString): Get content of field with specified ID from current result row
87+
- [DB_GetFieldStringByName](DB_GetFieldStringByName): Get content of field with specified name from current result row
88+
- [DB_GetFieldInt](DB_GetFieldInt): Get content of field as an integer with specified ID from current result row
89+
- [DB_GetFieldIntByName](DB_GetFieldIntByName): Get content of field as an integer with specified name from current result row
90+
- [DB_GetFieldFloat](DB_GetFieldFloat): Get content of field as a float with specified ID from current result row
91+
- [DB_GetFieldFloatByName](DB_GetFieldFloatByName): Get content of field as a float with specified name from current result row
92+
- [DB_GetMemHandle](DB_GetMemHandle): Get memory handle for an SQLite database that was opened with DB_Open.
93+
- [DB_GetLegacyDBResult](DB_GetLegacyDBResult): Get memory handle for an SQLite query that was executed with DB_ExecuteQuery.
94+
- [DB_GetDatabaseConnectionCount](DB_GetDatabaseConnectionCount): The function gets the number of open database connections for debugging purposes.
95+
- [DB_GetDatabaseResultSetCount](DB_GetDatabaseResultSetCount): The function gets the number of open database results.

‎frontend/docs/scripting/functions/DB_Open.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
---
2+
title: DB_Open
3+
sidebar_label: DB_Open
4+
description: The function is used to open a connection to a SQLite database file, which is inside the `/scriptfiles` folder.
5+
tags: ["sqlite"]
6+
---
7+
8+
## Description
9+
10+
The function is used to open a connection to a SQLite database, which is inside the "/scriptfiles" folder.
11+
12+
| Name | Description |
13+
| ------------------------------------------------------------------- | ----------------------------------------------------- |
14+
| const name[] | File name of the database |
15+
| SQLITE_OPEN:flags = SQLITE_OPEN_READWRITE | SQLITE_OPEN_CREATE | [Permissions / Flags](../resources/sqlite-open-flags) |
16+
17+
## Returns
18+
19+
Returns index (starting at 1) of the database connection.
20+
21+
## Examples
22+
23+
```c
24+
static DB:gDBConnectionHandle;
25+
26+
// ...
27+
28+
public OnGameModeInit()
29+
{
30+
// ...
31+
32+
// Create a connection to a database
33+
gDBConnectionHandle = DB_Open("example.db");
34+
35+
// If connection to the database exists
36+
if (gDBConnectionHandle)
37+
{
38+
// Successfully created a connection to the database
39+
print("Successfully created a connection to database \"example.db\".");
40+
}
41+
else
42+
{
43+
// Failed to create a connection to the database
44+
print("Failed to open a connection to database \"example.db\".");
45+
}
46+
47+
// ...
48+
49+
return 1;
50+
}
51+
52+
public OnGameModeExit()
53+
{
54+
// Close the connection to the database if connection is open
55+
if (DB_Close(gDBConnectionHandle))
56+
{
57+
// Extra cleanup
58+
gDBConnectionHandle = DB:0;
59+
}
60+
61+
// ...
62+
63+
return 1;
64+
}
65+
```
66+
67+
## Notes
68+
69+
:::warning
70+
71+
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)!
72+
73+
:::
74+
75+
## Related Functions
76+
77+
- [DB_Open](DB_Open): Open a connection to an SQLite database
78+
- [DB_Close](DB_Close): Close the connection to an SQLite database
79+
- [DB_ExecuteQuery](DB_ExecuteQuery): Query an SQLite database
80+
- [DB_FreeResultSet](DB_FreeResultSet): Free result memory from a DB_ExecuteQuery
81+
- [DB_GetRowCount](DB_GetRowCount): Get the number of rows in a result
82+
- [DB_SelectNextRow](DB_SelectNextRow): Move to the next row
83+
- [DB_GetFieldCount](DB_GetFieldCount): Get the number of fields in a result
84+
- [DB_GetFieldName](DB_GetFieldName): Returns the name of a field at a particular index
85+
- [DB_GetFieldString](DB_GetFieldString): Get content of field with specified ID from current result row
86+
- [DB_GetFieldStringByName](DB_GetFieldStringByName): Get content of field with specified name from current result row
87+
- [DB_GetFieldInt](DB_GetFieldInt): Get content of field as an integer with specified ID from current result row
88+
- [DB_GetFieldIntByName](DB_GetFieldIntByName): Get content of field as an integer with specified name from current result row
89+
- [DB_GetFieldFloat](DB_GetFieldFloat): Get content of field as a float with specified ID from current result row
90+
- [DB_GetFieldFloatByName](DB_GetFieldFloatByName): Get content of field as a float with specified name from current result row
91+
- [DB_GetMemHandle](DB_GetMemHandle): Get memory handle for an SQLite database that was opened with DB_Open.
92+
- [DB_GetLegacyDBResult](DB_GetLegacyDBResult): Get memory handle for an SQLite query that was executed with DB_ExecuteQuery.
93+
- [DB_GetDatabaseConnectionCount](DB_GetDatabaseConnectionCount): The function gets the number of open database connections for debugging purposes.
94+
- [DB_GetDatabaseResultSetCount](DB_GetDatabaseResultSetCount): The function gets the number of open database results.
95+
96+
## Related Resources
97+
98+
- [SQLite Open Flags](../resources/sqlite-open-flags)

0 commit comments

Comments
 (0)