From 999ae56226e72fd62fabfa23dabde1f80ae92cb1 Mon Sep 17 00:00:00 2001
From: Kerbiter
Date: Mon, 16 Sep 2024 00:07:41 +0300
Subject: [PATCH] Init docs (#1063)
---
.github/workflows/pr-doc-checker.yml | 80 +++++++++
.readthedocs.yaml | 25 +++
CREDITS.md | 9 +
README.md | 4 +-
docs/AI-Scripting-and-Mapping.md | 29 ++++
docs/CREDITS.md | 4 +
docs/Contributing.md | 121 +++++++++++++
docs/Fixed-or-Improved-Logics.md | 37 ++++
docs/General-Info.md | 20 +++
docs/License.md | 6 +
docs/Makefile | 20 +++
docs/Miscellanous.md | 7 +
docs/New-or-Enhanced-Logics.md | 23 +++
docs/User-Interface.md | 24 +++
docs/Whats-New.md | 56 ++++++
docs/_static/css/dark.css | 187 +++++++++++++++++++++
docs/_static/css/index.css | 243 +++++++++++++++++++++++++++
docs/_static/icons/auto.svg | 3 +
docs/_static/icons/dark.svg | 4 +
docs/_static/icons/light.svg | 4 +
docs/_static/icons/status.svg | 3 +
docs/_static/js/ini-block-maker.js | 53 ++++++
docs/_static/js/scheme-switcher.js | 96 +++++++++++
docs/_templates/layout.html | 13 ++
docs/conf.py | 66 ++++++++
docs/index.md | 24 +++
docs/make.bat | 35 ++++
docs/requirements.txt | 3 +
28 files changed, 1198 insertions(+), 1 deletion(-)
create mode 100644 .github/workflows/pr-doc-checker.yml
create mode 100644 .readthedocs.yaml
create mode 100644 CREDITS.md
create mode 100644 docs/AI-Scripting-and-Mapping.md
create mode 100644 docs/CREDITS.md
create mode 100644 docs/Contributing.md
create mode 100644 docs/Fixed-or-Improved-Logics.md
create mode 100644 docs/General-Info.md
create mode 100644 docs/License.md
create mode 100644 docs/Makefile
create mode 100644 docs/Miscellanous.md
create mode 100644 docs/New-or-Enhanced-Logics.md
create mode 100644 docs/User-Interface.md
create mode 100644 docs/Whats-New.md
create mode 100644 docs/_static/css/dark.css
create mode 100644 docs/_static/css/index.css
create mode 100644 docs/_static/icons/auto.svg
create mode 100644 docs/_static/icons/dark.svg
create mode 100644 docs/_static/icons/light.svg
create mode 100644 docs/_static/icons/status.svg
create mode 100644 docs/_static/js/ini-block-maker.js
create mode 100644 docs/_static/js/scheme-switcher.js
create mode 100644 docs/_templates/layout.html
create mode 100644 docs/conf.py
create mode 100644 docs/index.md
create mode 100644 docs/make.bat
create mode 100644 docs/requirements.txt
diff --git a/.github/workflows/pr-doc-checker.yml b/.github/workflows/pr-doc-checker.yml
new file mode 100644
index 000000000..9e26e666a
--- /dev/null
+++ b/.github/workflows/pr-doc-checker.yml
@@ -0,0 +1,80 @@
+name: Pull Request Check
+
+on:
+ pull_request:
+ types:
+ - opened
+ - reopened
+ - synchronize
+ - labeled
+ - unlabeled
+env:
+ BASE_BRANCH: ${{ github.event.pull_request.base.ref }}
+
+jobs:
+ Changelog-Check:
+ name: Changelog Mention
+ # If the Minor label is set, then workflow will not be executed
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v1
+ - name: Check that Changelog has been updated
+ run: |
+ # Check that Changelog has been updated
+ if (git diff --name-only $(git merge-base origin/$BASE_BRANCH HEAD) | grep ^docs/Whats-New.md$)
+ then
+ echo "Thank you for remembering to update the Changelog! 😋"
+ exit 0
+ else
+ echo "It looks like you forgot to update the Changelog! 🧐"
+ echo "Please, mention your changes in 'docs/Whats-New.md'."
+ exit 1
+ fi
+
+ Credits-Check:
+ name: Credits List Mention
+ # If the Minor label is set, then workflow will not be executed
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v1
+ - name: Check that Credits List has been updated
+ run: |
+ # Check that Credits List has been updated
+ if (git diff --name-only $(git merge-base origin/$BASE_BRANCH HEAD) | grep ^CREDITS.md$)
+ then
+ echo "Thank you for remembering to update the Credits List! 😋"
+ exit 0
+ else
+ echo "It looks like you forgot to update the Credits List! 🧐"
+ echo "Please, mention your contribution in 'CREDITS.md'."
+ exit 1
+ fi
+
+ Documentation-Check:
+ name: Documentation for Changes
+ # If the Minor label is set, then workflow will not be executed
+ runs-on: ubuntu-latest
+
+ steps:
+ - uses: actions/checkout@v1
+ - name: Check that Documentation has been updated
+ run: |
+ # Check that Documentation has been updated
+ if (git diff --name-only $(git merge-base origin/$BASE_BRANCH HEAD) | \
+ grep \
+ -e ^docs/New-or-Enhanced-Logics.md$ \
+ -e ^docs/Fixed-or-Improved-Logics.md$ \
+ -e ^docs/AI-Scripting-and-Mapping.md$ \
+ -e ^docs/User-Interface.md$ \
+ -e ^docs/Miscellanous.md$ \
+ )
+ then
+ echo "Thank you for remembering to add your changes to the docs! 😋"
+ exit 0
+ else
+ echo "It looks like you forgot to add your changes to the docs! 🧐"
+ echo "Please, document your changes."
+ exit 1
+ fi
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
new file mode 100644
index 000000000..3904ef940
--- /dev/null
+++ b/.readthedocs.yaml
@@ -0,0 +1,25 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+ os: ubuntu-22.04
+ tools:
+ python: "3.8"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+ configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+ - pdf
+
+# We recommend specifying your dependencies to enable reproducible builds:
+python:
+ install:
+ - requirements: docs/requirements.txt
diff --git a/CREDITS.md b/CREDITS.md
new file mode 100644
index 000000000..0b530cd85
--- /dev/null
+++ b/CREDITS.md
@@ -0,0 +1,9 @@
+# Credits
+
+This page lists all the individual contributions to the project by their author.
+
+- **Belonit (Gluk-v48)**:
+ - Check for Changelog/Documentation/Credits in Pull Requests
+ - Docs dark theme switcher
+- **Kerbiter (Metadorius)**:
+ - Initial doc setup
diff --git a/README.md b/README.md
index ffd31f7ef..e1716ba88 100644
--- a/README.md
+++ b/README.md
@@ -5,7 +5,9 @@
Vinifera is an open-source community collaboration project extending the Tiberian Sun engine.
-
+
+
+
diff --git a/docs/AI-Scripting-and-Mapping.md b/docs/AI-Scripting-and-Mapping.md
new file mode 100644
index 000000000..8fd117e83
--- /dev/null
+++ b/docs/AI-Scripting-and-Mapping.md
@@ -0,0 +1,29 @@
+# AI Scripting and Mapping
+
+This page describes all AI scripting and mapping related additions and changes introduced by Vinifera.
+
+## Bugfixes and Miscellanous
+
+TODO
+
+## Singleplayer Mission Maps
+
+TODO
+
+## Script Actions
+
+### `10000-10999` Some TODO range
+
+#### `10000-10049` Some TODO subrange
+
+TODO
+
+#### `10050` Some action
+
+TODO
+
+## Trigger Actions
+
+### `000` Some Action
+
+TODO
\ No newline at end of file
diff --git a/docs/CREDITS.md b/docs/CREDITS.md
new file mode 100644
index 000000000..4b45f5c61
--- /dev/null
+++ b/docs/CREDITS.md
@@ -0,0 +1,4 @@
+```{include} ../CREDITS.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/Contributing.md b/docs/Contributing.md
new file mode 100644
index 000000000..2887bb79c
--- /dev/null
+++ b/docs/Contributing.md
@@ -0,0 +1,121 @@
+# Contributing
+
+This page describes ways to help or contribute to Vinifera and lists the contributing guidelines that are used in the project.
+
+## Guidelines for contributors
+
+### Project structure
+
+TODO
+
+### Code styleguide
+
+TODO
+
+### Git branching model
+
+Couple of notes regarding the Git practices. We use [git-flow](https://nvie.com/posts/a-successful-git-branching-model/)-like workflow:
+ - `master` is for stable releases, can have hotfixes pushed to it or branched off like a feature branch with the requirement of version increment and `master` being merged into `develop` after that;
+ - `develop` is the main development branch;
+ - `feature/`-prefixed branches (sometimes the prefix may be different if appropriate, like for big fixes or changes) are so called "feature branches" - those are branched off `develop` for every new feature to be introduced into it and then merged back. We use squash merge to merge them back in case of smaller branches and sometimes merge commit in case the branch is so big it would be viable to keep it as is.
+ - `hotfix/`-prefixed branches may be used in a same manner as `feature/`, but with `master` branch, with a requirement of `master` being merged into `develop` after `hotfix/` branch was squash merged into `master`.
+ - `release/`-prefixed branches are branched off `develop` when a new stable release is slated to allow working on features for a next release and stability improvements for this release. Those are merged with a merge commit into `master` and `develop` with a stable version number increase, after which the stable version is released.
+- When you're working with your local & remote branches use **fast-forward** pulls to get the changes from remote branch to local, **don't merge remote branch into local and vice versa**, this creates junk commits and makes things unsquashable.
+
+These commands will do the following for all repositories on your PC:
+1) remove the automatic merge upon pull and replace it with a rebase;
+2) highlight changes consisting of moving existing lines to another location with a different color.
+
+```bash
+git config --global pull.rebase true
+git config --global branch.autoSetupRebase always
+git config --global diff.colorMoved zebra
+```
+
+## Ways to help
+
+Engine modding is a complicated process which is pretty hard to pull off, but there are also easier parts which don't require mastering the art of reverse-engineering or becoming a dank magician in C++.
+
+### Research and reverse-engineering
+
+You can observe how the stuff works by using the engine and note which other stuff influences the behavior, but sooner or later you would want to see the innards of that. This is usually done using such tools as disassemblers/decompilers ([IDA](https://www.hex-rays.com/products/ida/), [Ghidra](https://ghidra-sre.org/)) to decipher what is written in the binary (`gamemd.exe` in case of the binary) and debuggers ([Cheat Engine](https://www.cheatengine.org)'s debugger is pretty good for that) to trace how the binary works.
+
+```{hint}
+Reverse-engineering is a complex task, but don't be discouraged, if you want to try your hands at it ask us in the Discord channel, we will gladly help 😄
+```
+
+```{note}
+[Assembly language](https://www.cs.virginia.edu/~evans/cs216/guides/x86.html) and C++ knowledge, understanding of computer architecture, memory structure, OOP and compiler theory would certainly help.
+```
+
+### Development
+
+When you found out how the engine works and where you need to extend the logic you'd need to develop the code to achieve what you want. This is done by declaring a *hook* - some code which would be executed after the program execution reaches the certain address in binary. All the development is done in C++ using [TSpp](https://github.com/Vinifera-Developers/TSpp) (which provides a way to interact with TS code and inject code) and usually [Visual Studio 2019](https://visualstudio.microsoft.com).
+
+(contributing-changes-to-the-project)=
+#### Contributing changes to the project
+
+To contribute a feature or some sort of a change you you would need a Git client (We recommend [GitKraken](https://www.gitkraken.com/)). Fork, clone the repo, preferably make a new branch, then edit/add the code or whatever you want to contribute. Commit, push, start a pull request, wait for it to get reviewed, or merged.
+
+If you contribute something, please make sure:
+- you write documentation for the change;
+- you mention the change in the changelog and migration sections in the [what's new page](Whats-New.md);
+- you mention your contribution in the [credits page](CREDITS.md).
+
+```{hint}
+Every pull request push trigger a nightly build for the latest pushed commit, so you can check the build status at the bottom of PR page, press `Show all checks`, go to details of a build run and get the zip containing built DLL and PDB (for your testers, f. ex.), or download a build from an automatically posted comment.
+```
+
+```{note}
+You'd benefit from C++ experience, knowledge of programming patterns, common techniques etc. [Basic assembly knowledge](https://www.cs.virginia.edu/~evans/cs216/guides/x86.html) would help to correctly write the interaction with the memory where you hook at. Basic understanding of Git and GitHub is also needed.
+```
+
+### Testing
+
+This is a job that any modder (and even sometimes player) can do. Look at a new feature or a change, try to think of all possible cases when it can work differently, try to think of any possible logic flaws, edge cases, unforeseen interactions or conditions etc., then test it according to your thoughts. Any bugs should be reported to issues section of this repo, if possible.
+
+```{warning}
+**General stability** can only be achieved by extensive play-testing of new changes, both offline and online. Most modders have beta testing teams, so please, if you want the extension to be stable - contribute to that by having your testers play with the new features! Also the check-list below can help you identify issues quicker.
+```
+
+#### Testing check-list
+
+- **All possible valid use cases covered**. Try to check all of the valid feature use cases you can think of and verify that they work as intended with the feature.
+- **Correct saving and loading**. Most of the additions like new INI tags require storing them in saved object info. Sometimes this is not done correctly, especially on complex stuff (like radiation types). Please, ensure all the improvements work __identically__ before and after being saved and loaded (on the same version of Vinifera, of course).
+- **Interaction with other features**. Try to use the feature chained or interacting with other features from vanilla or other libs (for example, mind control removal warhead initially was crashing when trying to remove mind control from a permanently mind-controlled unit).
+- **Overlapping features not working correctly** (including those from third-party libs like Ares, HAres, CnCNet spawner DLL). Think of what features' code could overlap (in a technical sense; means they modify the same code) with what you're currently testing. Due to the nature of the project some features from other libs could happen to not work as expected if they are overlapping (for example, when implementing mass selection filtering Ares' `GroupAs` was initially broken and units using it weren't being type selected properly).
+- **Edge/corner cases**. Those are the cases of some specific cases usually induced by some extreme parameter values or the combination of them (for example, vanilla game crashes on zero-size `PreviewPack` instead of not drawing it).
+
+```{note}
+Knowledge on how to mod TS and having an inquisitive mind, being attentive to details would help.
+```
+
+### Writing docs
+
+No explanation needed. If you fully understand how some stuff in Vinifera works you can help by writing a detailed description in these docs, or you can just improve the pieces of docs you think are not detailed enough.
+
+The docs are written in Markdown (which is dead simple, [learn MD in 60 seconds](https://commonmark.org/help/); if you need help on extended syntax have a look at [MyST parser reference](https://myst-parser.readthedocs.io/)). We use [Sphinx](https://sphinx-doc.org/) to build docs, [Read the Docs](https://readthedocs.io/) to host.
+
+```{hint}
+You don't need to install Python, Sphinx and modules to see changes - every pull request you make is being built and served by Read the Docs automatically. Just like the nightly builds, scroll to the bottom, press `Show all checks` and see the built documentation in the details of a build run.
+```
+
+There are two ways to edit the docs.
+- **Edit from your PC**. Pretty much the same like what's described in [contributing changes section](contributing-changes-to-the-project); the docs are located in the `docs` folder.
+- **Edit via online editor**. Navigate to the doc piece that you want to edit, press the button on the top right - and it will take you to the file at GitHub which you would need to edit (look for the pencil icon to the top right). Press it - the fork will be created and you'll edit the docs in your version of the repo (fork). You can commit those changes (preferably to a new branch) and make them into a pull request to main repo.
+
+```{note}
+OK English grammar and understanding of docs structure would be enough. You would also need a GitHub account.
+```
+
+### Providing media to showcase features
+
+Those would be used in docs and with a link to the respective mod as a bonus for the mod author. To record GIFs you can use such apps as, for example, [GifCam](http://blog.bahraniapps.com/gifcam/).
+
+```{note}
+Please, provide screenshots, GIFs and videos in their natural size and without excess stuff or length.
+```
+
+### Promoting the work
+
+You can always help us by spreading the word about the project among people, whether you're an influential youtuber, a C&C related community leader or just an average player.
diff --git a/docs/Fixed-or-Improved-Logics.md b/docs/Fixed-or-Improved-Logics.md
new file mode 100644
index 000000000..1d1f97587
--- /dev/null
+++ b/docs/Fixed-or-Improved-Logics.md
@@ -0,0 +1,37 @@
+# Fixed / Improved Logics
+
+This page describes all ingame logics that are fixed or improved in Vinifera without adding anything significant.
+
+## Bugfixes and miscellaneous
+
+## Aircraft
+
+## Animations
+
+## Buildings
+
+## Particle systems
+
+## Particles
+
+## Projectiles
+
+## Technos
+
+## Terrains
+
+## Tiberiums (ores)
+
+## Vehicles
+
+## Veinholes & Weeds
+
+## VoxelAnims
+
+## Warheads
+
+## Weapons
+
+## Crate improvements
+
+## DropPod
diff --git a/docs/General-Info.md b/docs/General-Info.md
new file mode 100644
index 000000000..fe8e2922d
--- /dev/null
+++ b/docs/General-Info.md
@@ -0,0 +1,20 @@
+# General Info
+
+This page lists general info that should be known about the project.
+
+## Build types
+
+There are going to be three main types of Vinifera builds:
+- *stable builds* - those are numbered like your regular versions (something close to semantic versioning, e.g. version 1.2.3 for example) and ideally should contain no bugs, therefore are safe to use in mods;
+- *development builds* - those are the builds which contain functionality that needs to be tested. They are numbered plainly starting from 0 and incrementing the number on each release. Mod authors still can include those versions with their mods if they want latest features, though we can't guarantee lack of bugs;
+- *nightly builds* - bleeding edge versions which can include prototypes, proofs of concepts, scrapped features etc., in other words - we can't guarantee anything in those builds and they absolutely should NOT be used in mod releases and should only be used to help with development and testing.
+
+So far the development is at the stage when only nightly builds are produced.
+
+## Saved games filtering
+
+TODO
+
+## Compatibility
+
+Vinifera is designed to be used alongside [CnCNet TS patches and spawner](https://github.com/CnCNet/ts-patches) and eventually it's supposed to supersede them.
diff --git a/docs/License.md b/docs/License.md
new file mode 100644
index 000000000..2bd0a9f9c
--- /dev/null
+++ b/docs/License.md
@@ -0,0 +1,6 @@
+# License
+
+```{include} ../LICENSE.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/Makefile b/docs/Makefile
new file mode 100644
index 000000000..d4bb2cbb9
--- /dev/null
+++ b/docs/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 = .
+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)
diff --git a/docs/Miscellanous.md b/docs/Miscellanous.md
new file mode 100644
index 000000000..3e774aa59
--- /dev/null
+++ b/docs/Miscellanous.md
@@ -0,0 +1,7 @@
+# Miscellanous
+
+This page describes every change in Vinifera that wasn't categorized into a proper category yet.
+
+## Developer tools
+
+## INI
diff --git a/docs/New-or-Enhanced-Logics.md b/docs/New-or-Enhanced-Logics.md
new file mode 100644
index 000000000..0bcb48657
--- /dev/null
+++ b/docs/New-or-Enhanced-Logics.md
@@ -0,0 +1,23 @@
+# New / Enhanced Logics
+
+This page describes all the engine features that are either new and introduced by Vinifera or significantly extended or expanded.
+
+## New types / ingame entities
+
+## Animations
+
+## Buildings
+
+## Infantry
+
+## Projectiles
+
+## Super Weapons
+
+## Technos
+
+## Terrain
+
+## Warheads
+
+## Weapons
\ No newline at end of file
diff --git a/docs/User-Interface.md b/docs/User-Interface.md
new file mode 100644
index 000000000..dba0c9414
--- /dev/null
+++ b/docs/User-Interface.md
@@ -0,0 +1,24 @@
+# User Interface
+
+This page lists all user interface additions, changes, fixes that are implemented in Vinifera.
+
+## Bugfixes and miscellanous
+
+## Audio
+
+## Battle screen UI/UX
+
+## Hotkey Commands
+
+### `[ ]` Example command
+
+- Switches something. See [this](somewhere) for details.
+
+## Loading screen
+
+## Sidebar / Battle UI
+
+## Tooltips
+
+## Miscellanous
+
diff --git a/docs/Whats-New.md b/docs/Whats-New.md
new file mode 100644
index 000000000..168fb7363
--- /dev/null
+++ b/docs/Whats-New.md
@@ -0,0 +1,56 @@
+# What's New
+
+This page lists the history of changes across stable Vinifera releases and also all the stuff that requires modders to change something in their mods to accommodate.
+
+## Migrating
+
+% ```{hint}
+% You can use the migration utility (can be found on [Vinifera supplementaries repo](https://github.com/Vinifera-Developers/ViniferaSupplementaries)) to apply most of the changes automatically using a corresponding sed script file.
+% ```
+
+### From vanilla
+
+### When updating Vinifera
+
+### From TS Patches
+
+### New user settings in `SUN.ini`
+
+- These are new user setting keys added by various features in Vinifera. Most of them can be found in either in [user inteface](User-Interface.md) or [miscellaneous](Miscellanous.md) sections. Search functionality can be used to find them quickly if needed.
+
+```ini
+
+```
+
+### For Map Editor (Final Sun)
+
+
+ Click to show
+
+ In `FAData.ini`:
+ ```ini
+
+ ```
+
+
+## Changelog
+
+### 0.0
+
+
+ Click to show
+
+New:
+- Added something (by someone)
+
+Vanilla fixes:
+- Fixed something (by someone)
+
+Vinifera fixes:
+- Fixed something (by someone)
+
+Fixes / interactions with TS Patches:
+- Fixed something (by someone)
+
+
+
diff --git a/docs/_static/css/dark.css b/docs/_static/css/dark.css
new file mode 100644
index 000000000..d8e29ea0c
--- /dev/null
+++ b/docs/_static/css/dark.css
@@ -0,0 +1,187 @@
+.switcher__status {
+ background-color: #2b2c36;
+}
+
+.switcher__radio:focus-visible ~ .switcher__status {
+ outline: #fff solid 2px;
+}
+
+.switcher__radio--light,
+.switcher__radio--auto,
+.switcher__radio--dark {
+ filter: invert(1);
+}
+
+.switcher__radio--light:checked,
+.switcher__radio--auto:checked,
+.switcher__radio--dark:checked {
+ filter: invert(0);
+}
+
+:root {
+ color-scheme: dark;
+}
+
+.rst-content table.docutils thead,
+.wy-side-nav-search input[type="text"],
+.wy-side-nav-search input[type="text"]::placeholder,
+.wy-nav-content {
+ color: #d9d9d9 !important;
+ background: #2b2c36 !important;
+}
+
+.wy-body-for-nav {
+ background: #161b22 !important;
+}
+
+.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,
+.rst-versions,
+.wy-nav-side {
+ background-color: #23242b !important;
+}
+
+.wy-menu-vertical li.current > a button.toctree-expand {
+ color: #d9d9d9;
+}
+
+.wy-menu-vertical li.current > a,
+.wy-menu-vertical a {
+ color: #d9d9d9;
+ background-color: #23242b;
+}
+
+.wy-menu-vertical li.current > a:hover {
+ background-color: #3e3e4a;
+}
+
+.wy-menu-vertical li.toctree-l2 a {
+ color: #d9d9d9;
+ background-color: #2f3039;
+}
+
+.wy-menu-vertical li.toctree-l3 a {
+ color: #d9d9d9;
+ background-color: #3d3e4a;
+}
+
+.wy-menu-vertical li.toctree-l3.current > a,
+.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a {
+ background: #565766;
+}
+
+.wy-menu-vertical a:hover,
+.wy-menu-vertical li.current a:hover,
+.wy-menu-vertical li.toctree-l2.current > a:hover,
+.wy-menu-vertical li.toctree-l3.current > a:hover,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover,
+.wy-menu-vertical li.toctree-l3.current li.toctree-l4 > a:hover {
+ background: #5f5f6f !important;
+}
+
+.wy-menu-vertical li.current > a,
+.wy-menu-vertical li.on a {
+ background-color: #3d3e4a;
+}
+
+.wy-menu-vertical li.current > a:hover button.toctree-expand,
+.wy-menu-vertical li.toctree-l2 a:hover button.toctree-expand {
+ color: #d9d9d9;
+}
+
+.wy-menu-vertical li.toctree-l2.current > a,
+.wy-menu-vertical li.toctree-l2.current > a > button:hover,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a {
+ background: #3d3e4a;
+ color: #d9d9d9;
+}
+
+.wy-menu-vertical li.current a {
+ border: unset;
+}
+
+.admonition,
+.admonition-title,
+.rst-content img {
+ border-radius: 6px !important;
+}
+
+.highlight {
+ border-radius: 6px !important;
+ color: unset !important;
+ background-color: #161b22 !important;
+}
+
+.highlight-cpp,
+.highlight-ini {
+ border-style: none !important;
+}
+
+.highlight-ini .highlight pre {
+ line-height: 1.5 !important;
+}
+
+.highlight-ini .c1,
+.s {
+ color: unset !important;
+ font-style: inherit !important;
+}
+
+.highlight-ini .na,
+.k {
+ color: rgb(39, 174, 96) !important;
+ font-weight: unset !important;
+}
+
+.highlight-ini .o {
+ color: #7b8d80 !important;
+}
+
+.literal {
+ padding: 0.2em 0.4em !important;
+ margin: 1px !important;
+ color: unset !important;
+ background-color: rgb(240, 240, 250, 0.15) !important;
+ border-radius: 6px !important;
+ border-style: none !important;
+}
+
+.admonition .literal {
+ background-color: rgba(0, 0, 0, 0.25) !important;
+}
+
+.admonition-title {
+ border-radius: 6px 6px 0 0 !important;
+ background: rgb(0, 0, 0, 0.25) !important;
+}
+
+.hint {
+ background: rgb(90, 180, 90, 0.5) !important;
+}
+
+.warning {
+ background: rgba(190, 90, 90, 0.5) !important;
+}
+
+.note {
+ background: rgba(140, 140, 140, 0.5) !important;
+}
+
+.btn {
+ border-radius: 6px !important;
+ box-shadow: inset 0 -2px 0 0 rgba(0, 0, 0, 0.15) !important;
+ background-color: rgb(255, 255, 255, 0.15) !important;
+}
+
+a.btn.btn-neutral {
+ color: #d9d9d9 !important;
+}
+
+.btn:hover {
+ background-color: #2980b9 !important;
+}
+
+details {
+ color: #d9d9d9;
+ background-color: #24252d;
+ box-shadow: unset;
+}
diff --git a/docs/_static/css/index.css b/docs/_static/css/index.css
new file mode 100644
index 000000000..d4cb69ce3
--- /dev/null
+++ b/docs/_static/css/index.css
@@ -0,0 +1,243 @@
+:focus-visible {
+ outline: solid 2px;
+}
+
+.wy-nav-top i {
+ line-height: 54px;
+ padding-left: 10px;
+ padding-right: 10px;
+}
+
+.wy-nav-content {
+ max-width: none;
+}
+
+.rst-content code.literal {
+ white-space: nowrap;
+}
+
+.rst-content a {
+ color: #58a6ff;
+}
+
+.rst-content p img ~ em {
+ display: block;
+}
+
+.rst-content .btn:focus {
+ outline: unset;
+}
+
+.rst-content .btn:focus-visible {
+ outline: 2px solid;
+}
+
+.wy-body-for-nav {
+ background: #1a1a1a;
+ max-width: 1400px;
+ margin: auto;
+}
+
+.wy-nav-side {
+ left: auto;
+ max-width: 300px;
+}
+
+.wy-side-nav-search input[type="text"] {
+ border-radius: 6px;
+ box-shadow: unset;
+}
+
+.wy-side-nav-search input[type="text"]:focus-visible {
+ outline: solid 2px;
+}
+
+.wy-menu-vertical a:focus-visible {
+ outline-offset: -3px;
+}
+
+.wy-menu-vertical li.current > a,
+.wy-menu-vertical li.on a {
+ border-right: 1px solid #c9c9c9;
+}
+
+.wy-menu-vertical li.toctree-l2.current > a:hover,
+.wy-menu-vertical li.toctree-l2.current li.toctree-l3 > a:hover {
+ background: #d6d6d6;
+}
+
+.wy-menu-vertical li.toctree-l1.current > a {
+ border-bottom: unset;
+ border-top: unset;
+}
+
+.rst-versions {
+ left: auto;
+ width: 300px;
+ max-width: 85%;
+}
+
+.wy-grid-for-nav {
+ position: unset;
+}
+
+@media screen and (max-width: 768px) {
+ .wy-nav-side {
+ left: -300px;
+ }
+
+ .wy-nav-top {
+ padding: unset;
+ width: 100%;
+ position: fixed;
+ height: 50px;
+ }
+
+ .wy-nav-content-wrap.shift {
+ left: min(300px, 85%);
+ }
+
+ .rst-content {
+ padding-top: 50px;
+ }
+}
+
+.toctree-expand {
+ tab-in
+}
+
+details {
+ border: 1px solid rgba(0, 0, 0, 0.1);
+ border-radius: 4px;
+ background-color: #f3f6f6;
+ color: #404040;
+ box-shadow: inset 0 1px 2px -1px hsl(0deg 0% 100% / 50%),
+ inset 0 -2px 0 0 rgb(0 0 0 / 10%);
+ padding: 12px 12px 0;
+ margin-bottom: 24px;
+}
+
+summary {
+ font-style: italic;
+ cursor: pointer;
+ margin: -12px -12px 0;
+ padding: 12px;
+
+ -webkit-user-drag: none;
+ -webkit-user-select: none;
+ -moz-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+
+details[open] {
+ padding: 12px;
+}
+
+details[open] summary {
+ border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+ margin-bottom: 12px;
+}
+
+details > *:last-child {
+ margin-bottom: 0 !important;
+}
+
+/* =================================== */
+/* Switcher */
+
+.switcher {
+ position: absolute;
+ margin: 0;
+ display: grid;
+ grid-template-columns: 1fr 1fr 1fr;
+ border: none;
+ z-index: 200;
+ outline: unset !important;
+
+ /* margin-left: -50px; */
+ padding: 2px;
+ top: 12px;
+ left: 12px;
+}
+
+/* Switcher Legend */
+
+.switcher__legend {
+ position: absolute;
+ opacity: 0;
+ pointer-events: none;
+}
+
+/* Switcher Radio */
+
+.switcher__radio {
+ -webkit-appearance: none;
+ appearance: none;
+ margin: 0;
+ width: 22px;
+ height: 22px;
+ background-position: center;
+ background-repeat: no-repeat;
+ background-size: 16px;
+ transition: filter 0.1s ease-in;
+
+ margin-right: unset !important;
+}
+
+.switcher__radio:focus {
+ outline: unset !important;
+}
+
+.switcher__radio--light {
+ background-image: url("../icons/light.svg");
+}
+
+.switcher__radio--auto {
+ background-image: url("../icons/auto.svg");
+ background-size: 32px;
+}
+
+.switcher__radio--dark {
+ background-image: url("../icons/dark.svg");
+}
+
+/* Switcher Status */
+
+.switcher__status {
+ position: absolute;
+ top: 0;
+ right: 0;
+ bottom: 0;
+ left: 0;
+ z-index: -1;
+ border-radius: 18px;
+ background-color: #fcfcfc;
+ background-repeat: no-repeat;
+ background-image: url("../icons/status.svg");
+ background-size: 22px;
+ background-position: center;
+ transition: background-position 0.1s ease-in;
+}
+
+.switcher__radio:focus-visible ~ .switcher__status {
+ outline: #343131 solid 2px;
+}
+
+.switcher__radio--light:checked ~ .switcher__status {
+ background-position: left 2px center;
+}
+
+.switcher__radio--auto:checked ~ .switcher__status {
+ background-position: center center;
+}
+
+.switcher__radio--dark:checked ~ .switcher__status {
+ background-position: right 2px center;
+}
+
+.switcher__radio--light:checked,
+.switcher__radio--auto:checked,
+.switcher__radio--dark:checked {
+ filter: invert(1);
+}
diff --git a/docs/_static/icons/auto.svg b/docs/_static/icons/auto.svg
new file mode 100644
index 000000000..c9f84540a
--- /dev/null
+++ b/docs/_static/icons/auto.svg
@@ -0,0 +1,3 @@
+
diff --git a/docs/_static/icons/dark.svg b/docs/_static/icons/dark.svg
new file mode 100644
index 000000000..e544ee5a6
--- /dev/null
+++ b/docs/_static/icons/dark.svg
@@ -0,0 +1,4 @@
+
diff --git a/docs/_static/icons/light.svg b/docs/_static/icons/light.svg
new file mode 100644
index 000000000..08b5fe99a
--- /dev/null
+++ b/docs/_static/icons/light.svg
@@ -0,0 +1,4 @@
+
diff --git a/docs/_static/icons/status.svg b/docs/_static/icons/status.svg
new file mode 100644
index 000000000..22bcd91fd
--- /dev/null
+++ b/docs/_static/icons/status.svg
@@ -0,0 +1,3 @@
+
diff --git a/docs/_static/js/ini-block-maker.js b/docs/_static/js/ini-block-maker.js
new file mode 100644
index 000000000..f0cf9b77e
--- /dev/null
+++ b/docs/_static/js/ini-block-maker.js
@@ -0,0 +1,53 @@
+// Create an INI code block with given `newId` as a child of `parent` node, with an optional `height`
+function makeINICodeBlock(parent, newId, height) {
+ let div1 = document.createElement("div");
+ div1.className = "highlight-ini notranslate";
+ if (height != null) {
+ div1.style.height = `${height}px`;
+ div1.style.overflow = "auto";
+ }
+ let div2 = document.createElement("div");
+ div2.className = "highlight";
+ let pre = document.createElement("pre");
+ pre.id = newId;
+ div2.appendChild(pre);
+ div1.appendChild(div2);
+ parent.appendChild(div1);
+}
+
+// Add an INI line to a code block node (a direct parent
node)
+// An INI line consists of a `key`, `value` and `comment`, all can be null
+function addINILine(codeBlockNode, line) {
+ if (line.key != null) {
+ let na = document.createElement("span");
+ na.className = "na";
+ na.textContent = line.key;
+ codeBlockNode.appendChild(na);
+ let o = document.createElement("span");
+ o.className = "o";
+ o.textContent = "=";
+ codeBlockNode.appendChild(o);
+ }
+ if (line.value != null) {
+ let s = document.createElement("span");
+ s.className = "s";
+ s.textContent = line.value;
+ codeBlockNode.appendChild(s);
+ }
+ if (line.comment != null) {
+ if (line.key != null || line.value != null) {
+ let w = document.createElement("span");
+ w.className = "w";
+ w.textContent = ' ';
+ codeBlockNode.appendChild(w);
+ }
+ let c1 = document.createElement("span");
+ c1.className = "c1";
+ c1.textContent = line.comment;
+ codeBlockNode.appendChild(c1);
+ }
+ let w = document.createElement("span");
+ w.className = "w";
+ w.textContent = '\n';
+ codeBlockNode.appendChild(w);
+}
diff --git a/docs/_static/js/scheme-switcher.js b/docs/_static/js/scheme-switcher.js
new file mode 100644
index 000000000..5f77d7a50
--- /dev/null
+++ b/docs/_static/js/scheme-switcher.js
@@ -0,0 +1,96 @@
+const lightStyles = document.querySelectorAll('link[rel=stylesheet][media*=prefers-color-scheme][media*=light]');
+const darkStyles = document.querySelectorAll('link[rel=stylesheet][media*=prefers-color-scheme][media*=dark]');
+const darkSchemeMedia = matchMedia('(prefers-color-scheme: dark)');
+
+setupScheme();
+
+function createSchemeSwitcher()
+{
+ const div = document.createElement('fieldset');
+ div.className = "switcher";
+ div.innerHTML = `
+
+
+
+
+ `;
+ const switcher = document.querySelectorAll('.wy-side-nav-search').item(0);
+ switcher.before(div);
+
+ setupSwitcher();
+}
+
+function setupSwitcher() {
+ const switcherRadios = document.querySelectorAll('.switcher__radio');
+ const savedScheme = getSavedScheme();
+
+ if (savedScheme !== null) {
+ const currentRadio = document.querySelector(`.switcher__radio[value=${savedScheme}]`);
+ currentRadio.checked = true;
+ }
+
+ [...switcherRadios].forEach((radio) => {
+ radio.addEventListener('change', (event) => {
+ setScheme(event.target.value);
+ });
+ });
+}
+
+function setupScheme() {
+ const savedScheme = getSavedScheme();
+ const systemScheme = getSystemScheme();
+
+ if (savedScheme !== systemScheme) {
+ setScheme(savedScheme);
+ }
+}
+
+function setScheme(scheme) {
+ switchMedia(scheme);
+
+ if (scheme === 'auto') {
+ clearScheme();
+ } else {
+ saveScheme(scheme);
+ }
+}
+
+function switchMedia(scheme) {
+ let lightMedia;
+ let darkMedia;
+
+ if (scheme === 'auto') {
+ lightMedia = '(prefers-color-scheme: light)';
+ darkMedia = '(prefers-color-scheme: dark)';
+ } else {
+ lightMedia = (scheme === 'light') ? 'all' : 'not all';
+ darkMedia = (scheme === 'dark') ? 'all' : 'not all';
+ }
+
+ [...lightStyles].forEach((link) => {
+ link.media = lightMedia;
+ });
+
+ [...darkStyles].forEach((link) => {
+ link.media = darkMedia;
+ });
+}
+
+function getSystemScheme() {
+ const darkScheme = darkSchemeMedia.matches;
+
+ return darkScheme ? 'dark' : 'light';
+}
+
+function getSavedScheme() {
+ const result = localStorage.getItem('color-scheme');
+ return result ? result : 'auto';
+}
+
+function saveScheme(scheme) {
+ localStorage.setItem('color-scheme', scheme);
+}
+
+function clearScheme() {
+ localStorage.removeItem('color-scheme');
+}
diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
new file mode 100644
index 000000000..1904e4bea
--- /dev/null
+++ b/docs/_templates/layout.html
@@ -0,0 +1,13 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+ {{ super() }}
+
+
+
+
+
+{% endblock %}
+
+{% block footer %}
+
+{% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 000000000..7be8451f2
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,66 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Vinifera'
+copyright = '2024, The Vinifera Contributors'
+author = 'The Vinifera Contributors'
+
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ['sphinx_rtd_theme', 'myst_parser', 'sphinx.ext.mathjax']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+locale_dirs = ['locale/']
+gettext_compact = False
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+myst_heading_anchors = 3
+
+myst_enable_extensions = [
+ "amsmath",
+ "dollarmath",
+]
+
+html_theme_options = {
+ 'navigation_depth': 4,
+ # 'style_nav_header_background': '#408931',
+}
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 000000000..4fa20f18d
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,24 @@
+```{toctree}
+:hidden:
+:caption: Project Info
+General Info
+What's New
+Contributing
+Credits
+License
+```
+
+```{toctree}
+:hidden:
+:caption: Extension Documentation
+New / Enhanced Logics
+Fixed / Improved Logics
+AI Scripting and Mapping
+User Interface
+Miscellanous
+```
+
+```{include} ../README.md
+:relative-docs: docs/
+:relative-images:
+```
diff --git a/docs/make.bat b/docs/make.bat
new file mode 100644
index 000000000..922152e96
--- /dev/null
+++ b/docs/make.bat
@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+ set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+ echo.
+ echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+ echo.installed, then set the SPHINXBUILD environment variable to point
+ echo.to the full path of the 'sphinx-build' executable. Alternatively you
+ echo.may add the Sphinx directory to PATH.
+ echo.
+ echo.If you don't have Sphinx installed, grab it from
+ echo.http://sphinx-doc.org/
+ exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 000000000..955d4f97b
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,3 @@
+myst-parser==0.15.2
+Sphinx==4.2.0
+sphinx-rtd-theme==1.0.0