Create Github Pages Documentation (#752)

* Include basic mkdocs installation.

Update build to use one run instead of multiple.

TODO: Update build job to build and host files with GH Pages.

* Documentation conversion. Start with essentials.

Include build job for github pages.

Update example match json for new map pool.

* Update mkdocs and github action.

* Update published directory.

* Try once more.

* Change to a different build process.

* Another build change?

* Include space for commands for proper formatting.

* Remove redunant text in README and point to docs site.

* Swap URL.

* Branch update.

* Include colours from the utils class.

.github/workflows/build.yml

@@ -20,22 +20,22 @@ jobs:
       with:
         version: '1.10.x'
 
-    - run: wget $STEAMWORKS_URL -P steamworks
+    - run: | 
+        wget $STEAMWORKS_URL -P steamworks
+        mkdir -p $OUTPUT_SM_PATH/plugins/disabled
+        cp -R get5/cfg $OUTPUT_PATH
+        cp -R get5/translations $OUTPUT_SM_PATH
+        cp -R get5/configs $OUTPUT_SM_PATH
+        cp -R get5/scripting $OUTPUT_SM_PATH
+        cp get5/README.md $OUTPUT_PATH
+        cp get5/LICENSE $OUTPUT_PATH
+        spcomp get5/scripting/get5.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/get5.smx
+        spcomp get5/scripting/get5_apistats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_apistats.smx
+        spcomp get5/scripting/get5_mysqlstats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_mysqlstats.smx
 
-    - run: mkdir -p $OUTPUT_SM_PATH/plugins/disabled
-    - run: cp -R get5/cfg $OUTPUT_PATH
-    - run: cp -R get5/translations $OUTPUT_SM_PATH
-    - run: cp -R get5/configs $OUTPUT_SM_PATH
-    - run: cp -R get5/scripting $OUTPUT_SM_PATH
-    - run: cp get5/README.md $OUTPUT_PATH
-    - run: cp get5/LICENSE $OUTPUT_PATH
-    - run: spcomp get5/scripting/get5.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/get5.smx
-    - run: spcomp get5/scripting/get5_apistats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_apistats.smx
-    - run: spcomp get5/scripting/get5_mysqlstats.sp -i steamworks -i $SM_JSON_INC_PATH -o $OUTPUT_SM_PATH/plugins/disabled/get5_mysqlstats.smx
-
-    - run: mkdir -p artifacts
-    - run: tar -zcvf artifacts/get5.tar.gz $OUTPUT_PATH/
-    - run: zip -r artifacts/get5.zip $OUTPUT_PATH/
+        mkdir -p artifacts
+        tar -zcvf artifacts/get5.tar.gz $OUTPUT_PATH/
+        zip -r artifacts/get5.zip $OUTPUT_PATH/
 
     - uses: actions/upload-artifact@v2
       with:

.github/workflows/generate_docs.yml

@@ -0,0 +1,21 @@
+name: Publish MKDocs to GH Pages
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout main
+        uses: actions/checkout@v2
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        # Or use mhausenblas/mkdocs-deploy-gh-pages@nomaterial to build without the mkdocs-material theme
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: documentation/mkdocs.yml
+          EXTRA_PACKAGES: build-base

README.md

@@ -32,196 +32,7 @@ Features of this include:
 Get5 also aims to make it easy to build automation for it. Commands are added so that a remote server can manage get5, collect stats, etc. The [get5 web panel](https://github.com/splewis/get5-web) is an (functional) proof-of-concept for this.
 
 ## Download and Installation
-
-#### Requirements
-You must have sourcemod installed on the game server. You can download it at http://www.sourcemod.net/downloads.php. Note that sourcemod also requires MetaMod:Source to be on the server. You can download it at http://www.metamodsource.net/downloads.php. You must have a 1.9+ build of sourcemod.
-
-#### Download
-Download a release package from the [releases section](https://github.com/splewis/get5/releases) or [the latest development build](https://github.com/splewis/get5/actions/workflows/build.yml?query=branch%3Amaster++) (click the latest successful build from `branch:master` and download the artifact called `build`).
-
-Release and development builds are currently compiled against sourcemod 1.10 and should work on sourcemod 1.10 or later.
-
-#### Installation
-Extract the download archive into the csgo/ directory on the server. Once the plugin first loads on the server, you can edit general get5 cvars in the autogenerated ``cfg/sourcemod/get5.cfg``. You should also have 3 config files: ``cfg/get5/warmupcfg``, ``cfg/get5/knife.cfg``, ``cfg/get5/live.cfg``. These can be edited, but I recommend **not** blindly pasting another config in (e.g. ESL, CEVO). Configs that execute warmup commands (``mp_warmup_end``, for example) **will** cause problems.
-
-If you need more help, see the [step-by-step guide in the wiki](https://github.com/splewis/get5/wiki/Step-by-step-installation-guide).
-
-#### Optional steps/plugins
-
-The get5 releases contain 2 additional plugins, disabled by default. They are in ``addons/sourcemod/plugins/disabled``. To enable one, move it up a directory to ``addons/sourcemod/plugins``.
-
-##### get5_apistats
-
-``get5_apistats`` is for integration with the [get5 web panel](https://github.com/splewis/get5-web). You don't need it unless you're using the web panel. Note you need the [Steamworks](https://forums.alliedmods.net/showthread.php?t=229556) extension for this plugin.
-
-**NOTE**: The HTTP API requests this plugin sends are **not** part of a public API. They are the communication between this plugin and the [get5-web](https://github.com/splewis/get5-web) project; you should not rely on the API being stable. If you're a developer writing your own server listening to get5_apistats, consider forking the get5_apistats plugin and renaming it to something else.
-
-##### get5_mysqlstats
-
-``get5_mysqlstats``: is an optional plugin for recording match stats. To use it, create a "get5" section in your ``addons/sourcemod/configs/databases.cfg`` file and use [these MySQL commands](misc/import_stats.sql) to create the tables. You can also set ``get5_mysql_force_matchid`` to a matchid to make get5 ignore the matchid in match configs, and use the one in the cvar. Otherwise, the matchid will be set based on matchid returned by MySQL from the SQL ``insert`` statement.
-
-
-## Quickstart
-
-To use get5, you generally create a [match config](https://github.com/splewis/get5#match-schema). In this file, you'll set up the match - what players, what map(s), etc.
-
-
-Once you create the match config anywhere under the server's ``csgo`` directory, run ``get5_loadmatch <file>`` in the server console. Everything will happen automatically after that.
-
-If you don't want to create a match config, you can set ``get5_check_auths 0`` in ``cfg/sourcemod/get5.cfg`` and then run the ``get5_creatematch`` command once all players are in the server.
-
-Alternatively, you can also up your server for [scrims](https://github.com/splewis/get5/wiki/Using-get5-for-scrims) by creating a scrim template specifying your team and run ``get5_scrim`` in console.
-
-The ``!get5`` command in-game will let you run the ``get5_creatematch`` and ``get5_scrim`` via a simple menu.
-
-
-## Commands
-
-Generally admin commands will have a ``get5_`` prefix and must be used in console. Commands intended for general player usage are created with ``sm_`` prefixes, which means sourcemod automtically registers a ``!`` chat version of the command. (For example: sm_ready in console is equivalent to !ready in chat)
-
-Some client commands are available also for admin usage. For example, sm_pause and sm_unpause will force pauses if executed by the server (e.g., through rcon).
-
-#### Client Commands (these can be typed by all players in chat)
-- ``!ready``: marks a client's team as ready to begin
-- ``!unready``: marks a client's team as not-ready
-- ``!pause``: requests a freezetime pause
-- ``!unpause``: requests an unpause, requires the other team to confirm
-- ``!tech``: requests a technical pause (technical pauses have no time limit or max number of uses)
-- ``!coach``: moves a client to coach for their team
-- ``!stay``: elects to stay after a knife round win
-- ``!swap`` or ``!switch``: elects to swap team side after a knife round win
-- ``!stop``: asks to reload the last match backup file, requires other team to confirm
-- ``!forceready``: force readies your team, letting your team start regardless of player numbers/whether they are ready
-
-#### Server/Admin Commands (meant to be used by admins in console)
-- ``get5_loadmatch``: loads a match config file (JSON or keyvalues) relative from the ``csgo`` directory
-- ``get5_loadbackup``: loads a get5 backup file
-- ``get5_loadteam``: loads a team section from a file into a team
-- ``get5_loadmatch_url``: loads a remote (JSON formatted) match config by sending a HTTP(S) GET to the given url, this requires the [Steamworks](https://forums.alliedmods.net/showthread.php?t=229556) extension. When specifying an url with http:// or https:// in front, you have to put it in quotation marks. 
-- ``get5_endmatch``: force ends the current match
-- ``get5_creatematch``: creates a Bo1 match with the current players on the server on the current map
-- ``get5_scrim``: creates a Bo1 match with the using settings from ``configs/get5/scrim_template.cfg``
-- ``get5_addplayer``: adds a steamid to a team (any format for steamid)
-- ``get5_removeplayer``: removes a steamid from all teams (any format for steamid)
-- ``get5_addkickedplayer``: adds the last kicked steamid to a team
-- ``get5_removekickedplayer``: removes the last kicked steamid from all teams
-- ``get5_forceready``: marks all teams as ready
-- ``get5_dumpstats``: dumps current match stats to a file
-- ``get5_status``: replies with JSON formatted match state (available to all clients)
-- ``get5_listbackups``: lists backup files for the current matchid or a given matchid
-
-#### Other commands
-
-- ``!get5`` opens a menu that wraps some common commands. It's mostly intended for people using scrim settings, and has menu buttons for starting a scrim, force-starting, force-ending, adding a ringer, and loading the most recent backup file.
-
-## Match Schema
-
-See the example config in [Valve KeyValues format](configs/get5/example_match.cfg) or [JSON format](configs/get5/example_match.json) to learn how to format the configs. Both example files contain equivalent match data.
-
-Of the below fields, only the ``team1`` and ``team2`` fields are actually required. Reasonable defaults are used for entires (bo3 series, 5v5, empty strings for team names, etc.)
-
-- ``matchid``: a string matchid used to identify the match
-- ``num_maps``: number of maps in the series. This must be an odd number or 2.
-- ``maplist``: list of the maps in use (an array of strings in JSON, mapnames as keys for KeyValues), you should always use an odd-sized maplist
-- ``skip_veto``: whether the veto will be skipped and the maps will come from the maplist (in the order given)
-- ``veto_first``: either "team1", or "team2". If not set, or set to any other value, team 1 will veto first.
-- ``side_type``: either "standard", "never_knife", or "always_knife"; standard means the team that doesn't pick a map gets the side choice, never_knife means team1 is always on CT first, and always knife means there is always a knife round
-- ``players_per_team``: maximum players per team (doesn't include a coach spot, default: 5)
-- ``min_players_to_ready``: minimum players a team needs to be able to ready up (default: 1)
-- ``favored_percentage_team1``: wrapper for ``mp_teamprediction_pct``
-- ``favored_percentage_text`` wrapper for ``mp_teamprediction_txt``
-- ``cvars``: cvars to be set during the match warmup/knife round/live state
-- ``spectators``: see the team schema below (only the ``players`` and ``name`` sections are used for spectators)
-- ``team1``: see the team schema below
-- ``team2``: see the team schema below
-
-Fields you may use, you aren't generally needed to:
-- ``match_title``: wrapper on the ``mp_teammatchstat_txt`` cvar, but can use {MAPNUMBER} and {MAXMAPS} as variables that get replaced with their integer values. In a BoX series, you probably don't want to set this since get5 automatically sets mp_teamscore cvars for the current series score, and take the place of the mp_teammatchstat cvars.
-
-#### Team Schema
-Only ``name`` and ``players`` are required.
-
-- ``name``: team name (wraps ``mp_teamname_1`` and is displayed often in chat messages)
-- ``tag``: team tag (or short name), this replaces client "clan tags"
-- ``flag``: team flag (2 letter country code, wraps ``mp_teamflag_1``)
-- ``logo`` team logo (wraps ``mp_teamlogo_1``)
-- ``players``: list of Steam id's for users on the team (not used if ``get5_check_auths`` is set to 0). You can also force player names in here; in JSON you may use either an array of steamids or a dictionary of steamids to names.
-- ``series_score``: current score in the series, this can be used to give a team a map advantage or used as a manual backup method, defaults to 0
-- ``matchtext``: wraps ``mp_teammatchstat_1``, you probably don't want to set this, in BoX series mp_teamscore cvars are automatically set and take the place of the mp_teammatchstat cvars
-
-There is advice on handling these match configs in [the wiki](https://github.com/splewis/get5/wiki/Managing-match-configs).
-
-Instead of the above fields, you can also use "fromfile" and a filename, where that file contains the other above fields. This is available for both json and keyvalue format.s
-
-## ConVars
-These are auto-executed on plugin start by the auto-generated (the 1st time the plugin starts) file ``cfg/sourcemod/get5.cfg``.
-
-Please see [the wiki](https://github.com/splewis/get5/wiki/Full-list-of-get5-cvars) for a full list of cvars. You may also just look at the ``cfg/sourcemod/get5.cfg`` file directly on your server and see the cvar descriptions and values in the autogenerated file.
-
-You should either set these in the above file, or in the match config's ``cvars`` section.
-
-Note: cvars set in the ``cvars`` section will override other settings (standard CS:GO cvars are also supported).
-
-## API for developers
-
-Get5 can be interacted with in several ways. At a glance:
-
-1. You can write another SourceMod plugin that uses the [get5 natives and forwards](scripting/include/get5.inc). This is exactly what the [get5_apistats](scripting/get5_apistats.sp) and [get5_mysqlstats](scripting/get5_mysqlstats.sp) plugins do. Consider starting from those plugins and making any changes you want (forking the get5 plugin itself is strongly discouraged; but just making another plugin using the get5 plugin api like get5_apistats does is encouraged).
-
-1. You can read [event logs](https://github.com/splewis/get5/wiki/Event-logs) from a file on disk (set by ``get5_event_log_format``), through a RCON
-connection to the server console since they are output there, or through another sourcemod plugin (see #1).
-
-1. You can read the [stats](https://github.com/splewis/get5/wiki/Stats-system) get5 collects from a file on disk (set by ``get5_stats_path_format``), or through another sourcemod plugin (see #1).
-
-1. You can execute the ``get5_loadmatch`` command or ``get5_loadmatch_url`` commands via another plugin or via a RCON connection to begin matches. Of course, you could execute any get5 command you want as well.
-
-### Status schema
-
-The following is the `get_status` response's schema.
-
-#### Static part
-- `plugin_version`: Get5's version number.
-- `commit`: Only here if `COMMIT_STRING` is defined (probably not your case).
-- `gamestate`: A number representing the game's state.
-  - **0** - No setup has taken place.
-  - **1** - Warmup, waiting for the veto.
-  - **2** - Warmup, doing the veto.
-  - **3** - Setup done, waiting for players to ready up.
-  - **4** - In the knife round.
-  - **5** - Waiting for a !stay or !swap command after the knife.
-  - **6** - In the lo3 process.
-  - **7** - The match is live.
-  - **8** - Postgame screen + waiting for GOTV to finish broadcast.
-- `paused`: Is the match paused?
-- `gamestate_string`: A human-readable gamestate which is a translation of `gamestate`.
-  - `"none"`
-  - `"waiting for map veto"`
-  - `"map veto"`
-  - `"warmup"`
-  - `"knife round"`
-  - `"waiting for knife round decision"`
-  - `"going live"`
-  - `"live"`
-  - `"postgame"`
-
-#### Additional parts
-
-**If current game state isn't "none"**
-- `matchid`: The current match's id. You can set it in match configs, with the property which has the same name.
-- `loaded_config_file`: The name of the loaded config file. If you used `get5_loadmatch <file>`, it's this file's name. If you used `get5_loadmatch_url`, the pattern of the file is `remote_config%d.json`, where `%d` is the server's id, which you can set with `get5_server_id`.
-- `map_number`: The current map number in the series.
-- `team1` and `team2`: Two JSON objects which share the same properties.
-  - `name`: Name of the team.
-  - `series_score`: The score in the series.
-  - `ready`: Boolean indicating if the team is ready.
-  - `side`: The side on which the team is. Can be `"CT"`, `"T"` or `"none"`.
-  - `connected_clients`: The number of human clients connected in the team.
-  - `current_map_score`: The team's score on the current map.
-
-**If current game state is past the veto**
-- `maps`: A JSON object which contains one property per map.
-  - Key: `"map%d"`, where `%d` is the map index in the array.
-  - Value: The name of the map (taken from the match config).
+To see how to download and use Get5 on your game server, please visit the [documentation website](https://splewis.github.io/get5).
 
 ## Other things
 

configs/get5/example_match.json

@@ -19,13 +19,13 @@
 
 	"maplist":
 	[
-		"de_cache",
 		"de_dust2",
 		"de_inferno",
 		"de_mirage",
 		"de_nuke",
 		"de_overpass",
-		"de_train"
+		"de_train",
+		"de_vertigo"
 	],
 
 	"favored_percentage_team1": 65,