Documentation

.clang-format

@@ -1,3 +1,22 @@
+BasedOnStyle: Google
 UseTab: Always
 IndentWidth: 4
 TabWidth: 4
+ColumnLimit: 120
+
+Cpp11BracedListStyle: true
+SortIncludes: true
+IncludeBlocks: Regroup
+
+PointerAlignment: Right
+ReferenceAlignment: Right
+
+SpaceAfterCStyleCast: false
+SpaceBeforeParens: ControlStatements
+SpacesInAngles: Never
+SpaceInEmptyBlock: false
+AccessModifierOffset: -4
+
+AlignTrailingComments:
+    Kind: Always
+    OverEmptyLines: 1

.github/workflows/build-doc.yml

@@ -0,0 +1,84 @@
+name: "Build documentations"
+
+on:
+    push:
+        branches: ["main", "docs"]
+    pull_request:
+        branches: ["main", "docs"]
+    workflow_dispatch:
+
+env:
+    REPO: "rpgppengine/rpgpp"
+    RETENTION_DAYS: 7
+    DOCS_DIR: "build/html/"
+
+jobs:
+    build-docs:
+        name: "build docs"
+        runs-on: "ubuntu-latest"
+        env:
+            PLATFORM: linux
+            ARCH: x86_64
+
+        steps:
+            - name: Checkout repository
+              uses: actions/checkout@v6
+              with:
+                  fetch-depth: 0
+                  submodules: recursive
+
+            - name: Install Python
+              uses: actions/setup-python@v6
+              with:
+                  python-version: "3.13"
+
+            - name: Install packages
+              shell: bash
+              run: |
+                  sudo apt install doxygen
+            - name: Setup Python environment
+              shell: bash
+              run: |
+                  pip install -r requirements.txt
+
+            - name: Build
+              shell: bash
+              run: |
+                  mkdir -p build/
+                  doxygen doxygen.conf
+                  breathe-apidoc -o docs/Dev -m -f build/doxygen/xml
+                  make html
+
+            - name: Generate token
+              if: ${{ github.repository == env.REPO }}
+              id: generate_token
+              uses: actions/create-github-app-token@v3
+              with:
+                  app-id: ${{ secrets.DOC_PUSHER_APP_ID }}
+                  private-key: ${{ secrets.DOC_PUSHER_APP_SECRET }}
+                  owner: ${{ github.repository_owner }}
+
+            - name: Push to Destination
+              if: ${{ github.repository == env.REPO }}
+              run: |
+                  git config --global user.name "github-actions[bot]"
+                  git config --global user.email "github-actions[bot]@users.noreply.github.com"
+                  git clone https://x-access-token:${{ steps.generate_token.outputs.token }}@github.com/${{ github.repository_owner }}/docs.git dest
+
+                  cp -rf ${{ env.DOCS_DIR }}/* dest/
+                  cd dest
+                  if [[ -z "$(git status -s -uall)" ]]; then
+                      echo "No changes to commit"
+                      exit 0
+                  fi
+                  git add .
+                  git commit -m "Update documentation for ${{ github.repository }} at ${{ github.sha }}"
+                  git push origin main
+
+            - name: Upload artifact
+              uses: actions/upload-artifact@v6
+              with:
+                  name: docs
+                  path: ${{ env.DOCS_DIR }}
+                  if-no-files-found: error
+                  retention-days: ${{ env.RETENTION_DAYS }}

.gitignore

@@ -35,6 +35,9 @@
 *.pdb
 *.ilk
 
+# docs ignores
+docs/Dev
+
 game-src/*/lib/
 /editor
 /game
@@ -51,10 +54,10 @@ execs/**
 .vs/
 .vscode/
 .idea/
-docs/C++ API
 site/
 imgui.ini
 clangd/
 game-src/
+.venv/
 compile_commands.json
 xmake-*.exe

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = docs
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -1,55 +1,125 @@
 ![logo](readme/logo.png)
 ---
+
 [![Build RPG++](https://github.com/rpgppengine/rpgpp/actions/workflows/build.yml/badge.svg)](https://github.com/rpgppengine/rpgpp/actions/workflows/build.yml)
+[![Build documentations](https://github.com/rpgppengine/rpgpp/actions/workflows/build-doc.yml/badge.svg)](https://github.com/rpgppengine/rpgpp/actions/workflows/build-doc.yml)
+[![CodeQL Advanced](https://github.com/rpgppengine/rpgpp/actions/workflows/codeql.yml/badge.svg)](https://github.com/rpgppengine/rpgpp/actions/workflows/codeql.yml)
 
-RPG++ is an experimental 2D RPG game engine written in C++. It is currently in early development, but contributions are welcome!
+RPG++ is an experimental 2D RPG game engine and editor written in C++. It is currently in early development, but contributions are welcome!
 
 <img src="readme/readme_img1.png" alt="screenshot of engine" width="640">
 
 Requirements
 ---
-
-To build RPG++, you'll need to install the following tools/packages:
+To build RPG++, you will need the following tools and packages:
 - **For all platforms**:
   - [xmake](https://xmake.io/) (follow the instructions on the website to install XMake on your system)
   - [git](https://git-scm.com/)
-- Specifically for _Linux_:
-  - gcc, g++, make, and ninja (on Debian-based distros, you can install this via `sudo apt install build-essential`)
-  - libx11-dev, libxrandr-dev, libxinerama-dev, libxcursor-dev, libxi-dev, libgl1-mesa-dev, and mesa-common-dev (Debian-based distros can install this via `sudo apt install libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl1-mesa-dev mesa-common-dev`)
+- Specifically for _Linux_ (instructions to install packages are listed below):
+  - Packages: `gcc`, `g++`, `make`, `ninja`, `libx11-dev`, `libxrandr-dev`, `libxinerama-dev`, `libxcursor-dev`, `libxi-dev`, `libgl1-mesa-dev`, and `mesa-common-dev`
+  - Debian:
+	```bash
+	sudo apt install build-essential ninja-build libx11-dev libxrandr-dev libxinerama-dev libxcursor-dev libxi-dev libgl1-mesa-dev mesa-common-dev
+	```
+  - Fedora:
+	```bash
+	sudo dnf install gcc gcc-c++ make ninja-build libX11-devel libXrandr-devel libXinerama-devel libXcursor-devel libXi-devel mesa-libGL-devel
+	```
+  - Arch Linux:
+	```bash
+	sudo pacman -S base-devel ninja libx11 libxrandr libxinerama libxcursor libxi mesa
+	```
 - Specifically for _Windows_:
   - Visual Studio 2019 or later with Desktop development with C++ (community edition will suffice)
+- Specifically for _MacOS_:
+  - Xcode
 
-Building
+*Optionally*, if you like to contribute and build the documentations for RPG++, you will need the following tools and packages. Note that the building of documentations is not required to build the editor, and vice versa:
+- [Python version 3.12 or higher](https://www.python.org/) (to install Python, follow the specific instruction for your OS)
+- [doxygen](https://www.doxygen.nl/download.html)
+
+Building the RPG++ engine/editor
 ---
 
-Clone the project using git with
+1. Clone the project using git with
 
 ```bash
-git clone https://github.com/CDevv/rpgpp
+git clone https://github.com/rpgppengine/rpgpp.git
 ```
 
-To build all targets, run
+2. Build all targets by running the following commands (follow the instructions to install packages if there is one)
 
 ```bash
 xmake build --all
 ```
 
-If xmake failed to build, try force reinstalling the packages with
+_If xmake failed to build, try force reinstalling the packages with_
 ```bash
 xmake clean --all # remove build artifacts
 xmake require --clean # remove installed package cache for project
 xmake require --force # force install of package
 ```
 
-Running
+Building the documentations
 ---
+1. Create a Python environment if you haven't created one with
+```bash
+python -m venv .venv # you may need to specify a different command like "python3" if you have multiple versions of Python
+```
+
+2. Activate the environment with one of the following commands
+```bash
+# For Windows
+.venv\Scripts\activate.bat # cmd
+.venv\Scripts\Activate.ps1 # powershell
+# For Linux/MacOS
+source .venv/bin/activate # bash/zsh
+source .venv/bin/activate.fish # fish
+source .venv/bin/activate.csh # csh/tcsh
+```
 
-To start the editor, run
+3. Install the necessary packages with
+```bash
+pip install -r requirements.txt
+```
+4. Generate and build the docs with
+```bash
+xmake build_doc
+```
+or optionally, run each of the commands below __if the command above fails__:
+```bash
+mkdir -p build/
+doxygen doxygen.conf
+breathe-apidoc -o docs/Dev -m -f build/doxygen/xml
+make html
+```
+
+If you want to build documentation for the Lua API, you can run the following (you need to have [LuaLS](https://luals.github.io/)):
+```bash
+lua-language-server --doc=luasrc/ --doc_out_path=docs/userapi/
+```
+
+You should see the docs output at `build/html`.
+
+Running the editor
+---
+
+To start the RPG++ editor, run
 
 ```bash
 xmake run editor
 ```
 
+Serving the documentation
+---
+
+To serve the documentation, you can use any server hosting software. Make sure that the software is set to host at `build/html` within the repo.
+
+For example, to serve the documentation with Python's builtin `http.server`, run the following command within the root of the repo:
+```bash
+python -m http.server --directory build/html
+```
+
 Translation
 ---