Plugin/Handbook/README.md

# The SenseGlove Unreal Engine Handbook

## Prerequisites

- Brave Browser (for PDF generation; in case you have Brave installed in a non-conventional path, or you'd like to use a different Chromium-based browser you need to adjust the path inside the GNUmakefile).
- cygpath (Windows only) provided by [Git for Windows](https://gitforwindows.org/).
- GNU Make.
- Git.
- PowerShell (Windows only) required only by the `pack` make target.
- Python3 along with venv and pip. For Windows, a version of [WinPython](https://winpython.github.io/) is already shipped with this repo, so it's not an external requirement.
- Rsync and OpenSSH ([cwRsync](https://itefix.net/cwrsync) provides these for Windows) required only by the `deploy` make target.
- The Rust Toolchain and the Cargo package manager.
- Other common Unix utilities such as `awk`, `cp`, `cut`, `date`, `find`, `grep`, `hostname`, `mkdir`, `mktemp`, `mv`, `scp`, `sed`, `ssh`, `sort`, `tr`, and `uname` provided by most distors. On Windows these are mostly provided by [Git for Windows](https://gitforwindows.org/).
- `zip` command (Linux only) required only by the `pack` make target.

### Microsoft Windows Prerequisites Installation Notes

- Download and install [Git for Windows](https://gitforwindows.org/).
- Download and install [the Rust Toolchain](https://rustup.rs/).
- Download [a without-guile binary build of GNU Make for Windows from ezwinports](https://sourceforge.net/projects/ezwinports/files/), e.g. <code>make-4.4.1-without-guile-w32-bin.zip</code>.
- <code>make-\*-without-guile-w32-bin.zip/*</code> contents should be extracted and copied to your <code>Git\\mingw64\\</code>, e.g. <code>C:\\Program Files\\Git\\mingw64\\</code>, merging the folders, WITHOUT overwriting/replacing any existing files.
- After Git Bash installation, the changes to environment variables require a reboot. In order for these changes to take effect reboot the system, then proceed to the build section.
- Download and install [cwRsync](https://itefix.net/cwrsync) which is only required for the `deploy` make target. In case you won't intend to use that, this could be skipped.

## How to preview, build, and deploy?

In order to generate the handbook, on either GNU/Linux and Microsoft Windows everything is done through running the <code>make</code> command. Simply entering the <code>make</code> or <code>make help</code> inside your desired terminal will show you all the available make targets:

```sh
$ make help

Available make targets:

  - make build
  - make clean
  - make deploy
  - make help
  - make info
  - make serve
```

### make info

This target prints the build and version information.

### make clean

This target cleans up the output directory for the generated handbook, which is the <code>/Documentation</code> folder.

### make serve

This tatget could be used for viewing or live-previwing the handbook while editing simultaneously editing it. Simply run this tatget and leave your terminal open and inside your web browser of choice head to <code>http://localhost:8000/</code>. You can modify the handbook source code inside any text editor and upon saving your web browser will refresh in realtime once a change is detected.

### make build

This tatget builds the final handbook and outputs it to the <code>/Documentation</code> folder.

If you're building a release handbook, please make sure:

- You are either on a release tag, e.g. v2.1.0, or on the master branch.
- No commit has been made since the targeted tag.
- The Git tree state is clean.
- The Git version and plugin version match each other.

If you're building an unstable handbook for the next release, please make sure:

- You're building from the dev branch.
- The Git version value evaluates to empty.

### make deploy

This tatget is used to build and upload the final draft of the handbook. This tatget first runs the <code>clean</code> target and then the <code>build</code> target; and only then attempts to upload the content. Thus, any rule that applies to the <code>build</code> target, will apply to this target as well.

_Noete_: Building on Windows requires sourcing the deployment configuration file, otherwise the deployment will fail; e.g.:

```sh
$ source /c/Users/mamadou/AppData/Local/SenseGlove/ue-handbook/deploy.conf && make deploy
```

Also, on Windows you probably need to adjust the follwoing variables at the top of the `GNUmakefile`:

```make
SG_RSYNC_BIN_PATH_WINDOWS		:=	C:\Program Files\cwrsync\bin
SG_RSYNC_BINARY_PATH_WINDOWS		:=	$(SG_RSYNC_BIN_PATH_WINDOWS)\rsync.exe
SG_RSYNC_SSH_BINARY_PATH_WINDOWS	:=	$(SG_RSYNC_BIN_PATH_WINDOWS)\ssh.exe
```

### make pack

This target is meant to be used by the `sgum-packager` utility located in the [Packager](../Packager) folder in order to deploy the documentation in various formats along with the plugin to the Unreal Engine Marketplace.