Add documentation for getting started and writing plugins

.gitignore

@@ -8,11 +8,14 @@
 *~
 *.class
 *.iml
-
+.project
+.classpath
+**/bin/
 /game/data/rsa.pem
 /game/data/savedGames
 /lib/
 */target/
 */build/
 **/build/
-**/out/
+**/out/
+/vendor/

azure-pipelines.yml

@@ -1,47 +1,86 @@
-pool:
-  vmImage: 'ubuntu-latest'
-
 variables:
   GRADLE_USER_HOME: $(Pipeline.Workspace)/.gradle
 
-steps:
-  - task: CacheBeta@0
-    inputs:
-      key: $(Agent.OS)
-      path: $(GRADLE_USER_HOME)
-    displayName: "Gradle: setup build cache"
-
-  - task: SonarCloudPrepare@1
-    inputs:
-      SonarCloud: 'apollo-rsps-sonarcloud'
-      organization: 'apollo-rsps'
-      scannerMode: 'Other'
-    displayName: "SonarCloud: prepare analysis"
-
-  - task: Gradle@2
-    displayName: "Gradle: build"
-    inputs:
-      workingDirectory: ''
-      gradleWrapperFile: 'gradlew'
-      gradleOptions: '-Xmx3072m -Dorg.gradle.parallel=true -Dorg.gradle.caching=true -Dsonar.host.url=https://sonarcloud.io'
-      javaHomeOption: 'JDKVersion'
-      jdkVersionOption: '1.8'
-      jdkArchitectureOption: 'x64'
-      publishJUnitResults: true
-      testResultsFiles: '**/TEST-*.xml'
-      tasks: 'check jacocoTestReport sonarqube'
-
-  - script: |
-      ./gradlew --stop
-    displayName: "Gradle: stop daemon"
-
-  - task: SonarCloudPublish@1
-    inputs:
-      pollingTimeoutSec: '300'
-    displayName: "SonarCloud: publish quality gate"
+jobs:
+#- job: game_build
+#  timeoutInMinutes: 15
+#
+#  pool:
+#    vmImage: 'ubuntu-latest'
+#
+#  steps:
+#    - task: CacheBeta@0
+#      inputs:
+#        key: $(Agent.OS)
+#        path: $(GRADLE_USER_HOME)
+#      displayName: "Gradle: setup build cache"
+#
+#    - task: SonarCloudPrepare@1
+#      inputs:
+#        SonarCloud: 'apollo-rsps-sonarcloud'
+#        organization: 'apollo-rsps'
+#        scannerMode: 'Other'
+#      displayName: "SonarCloud: prepare analysis"
+#
+#    - task: Gradle@2
+#      displayName: "Gradle: build"
+#      inputs:
+#        workingDirectory: ''
+#        gradleWrapperFile: 'gradlew'
+#        gradleOptions: '-Xmx3072m -Dorg.gradle.parallel=true -Dorg.gradle.caching=true -Dsonar.host.url=https://sonarcloud.io'
+#        javaHomeOption: 'JDKVersion'
+#        jdkVersionOption: '1.11'
+#        jdkArchitectureOption: 'x64'
+#        publishJUnitResults: true
+#        testResultsFiles: '**/TEST-*.xml'
+#        tasks: 'check jacocoTestReport sonarqube'
+#
+#    - script: |
+#        ./gradlew --stop
+#      displayName: "Gradle: stop daemon"
+#
+#    - task: SonarCloudPublish@1
+#      inputs:
+#        pollingTimeoutSec: '300'
+#      displayName: "SonarCloud: publish quality gate"
+#
+#    - script: |
+#        bash <(curl -s https://codecov.io/bash) -t "${CODECOV_TOKEN}"
+#      env:
+#        CODECOV_TOKEN: $(CODECOV_TOKEN)
+#      displayName: "Codecov: publish coverage"
 
-  - script: |
-      bash <(curl -s https://codecov.io/bash) -t "${CODECOV_TOKEN}"
-    env:
-      CODECOV_TOKEN: $(CODECOV_TOKEN)
-    displayName: "Codecov: publish coverage"
+- job: docs_build
+  pool:
+    vmImage: 'windows-2019'
+  steps:
+    - task: Gradle@2
+      displayName: "Gradle: generate API docs"
+      inputs:
+        workingDirectory: ''
+        gradleWrapperFile: 'gradlew'
+        gradleOptions: '-Xmx3072m -Dorg.gradle.parallel=true -Dorg.gradle.caching=true -Dsonar.host.url=https://sonarcloud.io'
+        javaHomeOption: 'JDKVersion'
+        jdkVersionOption: '1.11'
+        jdkArchitectureOption: 'x64'
+        tasks: 'generateApiDocs'
+    - task: CmdLine@1
+      displayName: 'Chocolatey: install DocFX'
+      inputs:
+        filename: choco
+        arguments: 'install docfx -y'
+    - task: CmdLine@1
+      displayName: 'DocFX: generate documentation'
+      inputs:
+        filename: docfx
+        arguments: docs/docfx.json
+    - task: ArchiveFiles@2
+      inputs:
+        rootFolderOrFile: docs/_site
+        includeRootFolder: false
+        archiveFile: '$(Build.ArtifactStagingDirectory)/docs.zip'
+        replaceExistingArchive: true
+    - task: PublishBuildArtifacts@1
+      inputs:
+        pathToPublish: '$(Build.ArtifactStagingDirectory)/docs.zip'
+        artifactName: 'docs.zip'

docs/.gitignore

@@ -0,0 +1,9 @@
+###############
+#    folder   #
+###############
+/**/DROP/
+/**/TEMP/
+/**/packages/
+/**/bin/
+/**/obj/
+_site

docs/Dockerfile

@@ -0,0 +1,22 @@
+FROM mono:latest
+
+RUN apt-get update -y && apt-get install -y unzip git
+
+RUN mkdir -p /docfx
+WORKDIR /docfx
+RUN curl -L https://github.com/dotnet/docfx/releases/download/v2.44/docfx.zip -O \
+  && unzip docfx.zip \
+  && chmod +r /docfx
+
+RUN echo "#!/bin/bash" >> /usr/local/bin/docfx \
+   && echo "mono /docfx/docfx.exe \"\$@\"" >> /usr/local/bin/docfx \
+   && chmod +x /usr/local/bin/docfx
+
+RUN mkdir -p /srv/project \
+  && useradd -u 1000 docfx \
+  && chown docfx:docfx /srv/project
+
+USER docfx
+WORKDIR /srv/project
+
+ENTRYPOINT ["docfx"]

docs/api/.gitignore

@@ -0,0 +1,5 @@
+###############
+#  temp file  #
+###############
+*.yml
+.manifest

docs/api/core/.gitignore

@@ -0,0 +1 @@
+*.yml

docs/api/index.md

@@ -0,0 +1,2 @@
+# PLACEHOLD
+TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!

docs/api/plugin-script/on_button.md

@@ -0,0 +1,5 @@
+---
+uid: on_button
+---
+
+`on_button` allows registering @"handlers"

docs/build.gradle

@@ -0,0 +1,25 @@
+configurations {
+    doclet {
+        transitive(true)
+    }
+}
+
+dependencies {
+    doclet files("vendor/docfx-doclet-1.0-SNAPSHOT-jar-with-dependencies.jar")
+}
+
+
+gradle.projectsEvaluated {
+    task generateApiDocs(type: Javadoc) {
+            source = project(":game").sourceSets.main.java.sourceDirectories
+            classpath = project(":game").configurations.runtimeClasspath + project(":game").sourceSets.main.output
+            dependsOn(project(":game").assemble)
+
+        options.encoding 'UTF-8'
+        destinationDir = file("build/generated-files")
+        options.addStringOption("doclet", "com.microsoft.doclet.DocFxDoclet")
+        options.docletpath = configurations.doclet.toList()
+
+    }
+
+}

docs/docfx.json

@@ -0,0 +1,61 @@
+{
+  "build": {
+    "globalMetadata": {
+      "_appTitle": "Apollo Documentation",
+      "_gitContribute": {
+        "repo": "https://github.com/apollo-rsps/apollo",
+        "branch": "kotlin-experiments"
+      }
+    },
+    "content": [
+      {
+        "files": [
+          "api/**.yml",
+          "api/**.md"
+        ]
+      },
+      {
+        "files": [
+          "guide/**.md",
+          "guide/**/toc.yml",
+          "toc.yml",
+          "*.md"
+        ]
+      },
+      {
+        "files": [
+          "plugin-api/toc.yml",
+          "plugin-api/spec/**.yml"
+        ]
+      }
+    ],
+    "resource": [
+      {
+        "files": [
+          "images/**"
+        ]
+      }
+    ],
+    "overwrite": [
+      {
+        "files": [
+          "plugin-api/overwrites/**.md"
+        ],
+        "exclude": [
+          "obj/**",
+          "_site/**"
+        ]
+      }
+    ],
+    "dest": "_site",
+    "globalMetadataFiles": [],
+    "fileMetadataFiles": [],
+    "template": [ "default", "templates/material" ],
+    "postProcessors": [],
+    "markdownEngineName": "markdig",
+    "noLangKeyword": false,
+    "keepFileLink": false,
+    "cleanupCacheHistory": false,
+    "disableGitFeatures": false
+  }
+}

docs/guide/getting-started/01-setting-up-environment.md

@@ -0,0 +1,7 @@
+# Setting up a development environment
+
+## Prerequisites
+
+- **RuneScape game data**:  The cache files containing the game data for release 377 of RuneScape.
+
+- **JDK 8+**: An installation of the JDK is needed to run Gradle build tasks and run the server.

docs/guide/getting-started/02-running-apollo.md

@@ -0,0 +1,84 @@
+This is a short guide to getting a copy of Apollo from our VCS and
+running a server able to accept connections from a game client. It
+assumes you’re starting fresh and have no local copy of Apollo.
+
+Requirements
+============
+
+You should be familiar with running programs on the UNIX shell or
+Windows command prompt. There is also a short list of prerequisites
+below needed to complete this guide.
+
+-   Git
+-   Gradle
+-   Java 8
+-   RuneScape r377 game data files [1]
+
+Getting Apollo
+==============
+
+> **Note**
+>
+> Apollo is still in a development phase and has no current stable
+> release, so to run the server we need to build it from sources first.
+
+The URL for the Apollo git repository is
+<https://github.com/apollo-rsps/apollo.git>. You can clone this using
+the `git` command-line client or by using the [GitHub desktop
+client](https://help.github.com/desktop/guides/contributing-to-projects/cloning-a-repository-from-github-desktop/).
+
+```
+> $ git clone <https://github.com/apollo-rsps/apollo.git>
+```
+
+If using the command line client, the repository will now be under a
+folder named *apollo* and is ready to build. When complete open a shell
+or Windows command prompt in that directory and move to the next step.
+
+Building Apollo
+===============
+
+Apollo uses Gradle build scripts as it’s build system. To build it,
+create a command prompt or shell in the Apollo repository folder and
+run:
+
+```
+> $ ./gradlew assemble genRsa
+```
+
+This will build the core server with the content plugins and run their
+respective tests. This process takes around a minute to complete and
+when done will generate and output a set of RSA key parameters used by
+connecting clients to encrypt their credentials. Save these for later.
+
+Starting Apollo
+===============
+
+The last dependency is putting the game data in a location where the
+server can find it. By default Apollo looks under `data/fs` in the root
+directory for a folder matching the release number. Apollo supports
+release 377, so in our case we want the directory structure to look like
+this:
+
+```
+data/fs
+└── 377
+    ├── jingle1.mid
+    ├── main_file_cache.dat
+    ├── main_file_cache.idx0
+    ├── main_file_cache.idx1
+    ├── main_file_cache.idx2
+    ├── main_file_cache.idxN
+```
+
+Now that everything is in place we can use the Gradle task to boot the
+server.
+
+```
+> $ gradle server:run
+```
+
+After booting Apollo will have loaded the game data and be ready to accept connections.
+
+[1] We are unable to provide user-end assets like the game data or
+client due to copyright restrictions.