Add tools for maintaining the docs

.gitignore

@@ -80,6 +80,8 @@ local.properties
 
 # eclipse
 .project
+.classpath
+.factorypath
 
 # sbteclipse plugin
 .target

source/contributing/implementation/datamanipulator.rst

@@ -46,15 +46,15 @@ The following snippet shows the imports/paths for some classes in SpongeCommon t
 
 .. code-block:: java
 
-    org.spongepowered.common.data.DataProcessor
-    org.spongepowered.common.data.ValueProcessor
-    org.spongepowered.common.data.manipulator.immutable.entity.ImmutableSpongeHealthData
-    org.spongepowered.common.data.manipulator.mutable.common.AbstractData
-    org.spongepowered.common.data.manipulator.mutable.entity.SpongeHealthData
-    org.spongepowered.common.data.processor.common.AbstractEntityDataProcessor
-    org.spongepowered.common.data.util.DataConstants
-    org.spongepowered.common.data.util.NbtDataUtil
-    org.spongepowered.common.registry.type.data.KeyRegistryModule
+    import org.spongepowered.common.data.DataProcessor;
+    import org.spongepowered.common.data.ValueProcessor;
+    import org.spongepowered.common.data.manipulator.immutable.entity.ImmutableSpongeHealthData;
+    import org.spongepowered.common.data.manipulator.mutable.common.AbstractData;
+    import org.spongepowered.common.data.manipulator.mutable.entity.SpongeHealthData;
+    import org.spongepowered.common.data.processor.common.AbstractEntityDataProcessor;
+    import org.spongepowered.common.data.util.DataConstants;
+    import org.spongepowered.common.data.util.NbtDataUtil;
+    import org.spongepowered.common.registry.type.data.KeyRegistryModule;
 
 
 1. Implement the DataManipulator

source/plugin/commands/creating.rst

@@ -117,7 +117,7 @@ Perform an ``instanceof`` check to determine the type of the :javadoc:`CommandSo
     import org.spongepowered.api.command.source.CommandBlockSource;
     import org.spongepowered.api.command.source.ConsoleSource;
 
-    if(src instanceof Player) {
+    if (src instanceof Player) {
         Player player = (Player) src;
         player.sendMessage(Text.of("Hello " + player.getName() + "!"));
     }

source/plugin/data/custom/serialization.rst

@@ -76,7 +76,7 @@ two methods:
     import org.spongepowered.api.data.Queries;
     import org.spongepowered.api.data.MemoryDataContainer;
 
-    String name = "Spongie";
+    private String name = "Spongie";
 
     @Override
     public DataContainer toContainer() {

source/plugin/entities/ai.rst

@@ -91,7 +91,7 @@ Tasks
 The behavior of many entity types is similar to each other. For this reason, the entity AI split into multiple
 smaller and reusable parts called :javadoc:`AITask`\s. Each of the ``AITask``\s represents a single behavior trait of an
 entity such as :javadoc:`AITaskTypes#WATCH_CLOSEST {WATCH_CLOSEST}`, which makes the entity look at the nearest matching
-entity, or :javadoc:`AITask#AVOID_ENTITY {AVOID_ENTITY}`, which makes the entity flee from certain matching entities.
+entity, or :javadoc:`AITaskTypes#AVOID_ENTITY {AVOID_ENTITY}`, which makes the entity flee from certain matching entities.
 
 .. note::
 

source/plugin/injection.rst

@@ -13,6 +13,7 @@ Dependency Injection
     org.spongepowered.api.plugin.PluginContainer
     org.spongepowered.api.plugin.PluginManager
     org.spongepowered.api.scheduler.Scheduler
+    ninja.leaping.configurate.commented.CommentedConfigurationNode
     ninja.leaping.configurate.loader.ConfigurationLoader
     ninja.leaping.configurate.objectmapping.GuiceObjectMapperFactory
 

source/plugin/items/creating.rst

@@ -108,7 +108,7 @@ An example is shown below:
         Entity item = extent.createEntity(EntityTypes.ITEM, spawnLocation.getPosition());
         item.offer(Keys.REPRESENTED_ITEM, superMegaAwesomeSword.createSnapshot());
 
-        try (StackFrame frame = Sponge.getCauseStackManager().pushStackFrame()) {
+        try (StackFrame frame = Sponge.getCauseStackManager().pushCauseFrame()) {
             frame.addContext(EventContextKeys.SPAWN_TYPE, SpawnTypes.PLACEMENT);
             extent.spawnEntity(item);
         }

source/plugin/ray-tracing.rst

@@ -95,7 +95,7 @@ in front of the player.
     import org.spongepowered.api.util.blockray.BlockRayHit;
     import java.util.Optional;
 
-    BlockRay<World> blockRay;
+    BlockRay<World> blockRay = ...;
     Optional<BlockRayHit<World>> hitOpt = blockRay.end();
     if (hitOpt.isPresent()) {
         BlockRayHit<World> hit = hitOpt.get();

source/plugin/services.rst

@@ -47,7 +47,7 @@ Designing the API this way makes Sponge extremely modular.
     Plugins should provide options to not install their providers if the plugin is not dedicated to a single function.
 
 Example: Providing a simple warp service
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The first step is optional, but recommended. You specify the public methods of your service class in an interface:
 
@@ -94,7 +94,7 @@ the interface) and replace your version.
 
 .. code-block:: java
 
-    Sponge.getServiceManager().setProvider(yourPluginInstance, WarpService.class, new SimpleWarpService());
+    Sponge.getServiceManager().setProvider(plugin, WarpService.class, new SimpleWarpService());
 
 Other plugins can now access your service through the service manager:
 

tools/.gitignore

@@ -0,0 +1 @@
+!src/

tools/README.md

@@ -0,0 +1,7 @@
+Docs-Tools
+==========
+
+This package contains a number of tools that help maintaining the docs.
+
+* [Javadoc-Checker](javadoc-checker) - Checks imports and javadoc-references
+* [Code-Checker](code-checker) - Extracts code blocks and wraps them in proper classes

tools/code-checker/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) SpongePowered <https://www.spongepowered.org>
+Copyright (c) contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

tools/code-checker/README.md

@@ -0,0 +1,42 @@
+Code-Checker
+============
+
+A helper to extract the code blocks from the docs for the analysis, whether the code still compiles and is up to date.
+
+Requirements
+------------
+
+* Java 10
+* Maven 3.5
+
+Usage
+-----
+
+This application takes two optional parameters: `[path_to_SpongeDocs/sources [path_for_generated_sources]]`
+
+There a two variants to run this project.
+
+### Direct
+
+The simplest one is just run the following command in the command line:
+
+````bash
+mvn
+````
+
+This way assumes it is executed from within the SpongeDocs repo.
+
+You can also pass command line arguments to this like:
+
+````bash
+mvn -Dexec.args="../../source target/generated-sources/codeblocks"
+````
+
+### Stand-alone
+
+Or you can build the jar and then run it:
+
+````bash
+mvn clean package
+java -jar code-checker-x.y.z.jar <args...>
+````

tools/code-checker/pom.xml

@@ -0,0 +1,183 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+	<modelVersion>4.0.0</modelVersion>
+
+	<groupId>org.spongepowered.doctools</groupId>
+	<artifactId>code-checker</artifactId>
+	<version>1.0.0-SNAPSHOT</version>
+
+	<name>SpongeDocs Code Checker</name>
+	<description>A helper to extract the code blocks from the docs for the analysis,
+		whether the code still compiles and is up to date.</description>
+	<url>https://docs.spongepowered.org/</url>
+	<inceptionYear>2018</inceptionYear>
+
+	<licenses>
+		<license>
+			<name>The MIT License</name>
+			<url>https://opensource.org/licenses/MIT</url>
+		</license>
+	</licenses>
+
+	<organization>
+		<name>SpongePowered</name>
+		<url>https://www.spongepowered.org/</url>
+	</organization>
+
+	<properties>
+		<sponge.api.version>7.1.0</sponge.api.version>
+
+		<java.version>11</java.version>
+		<maven.compiler.source>${java.version}</maven.compiler.source>
+		<maven.compiler.target>${java.version}</maven.compiler.target>
+
+		<charset>UTF-8</charset>
+		<project.reporting.outputEncoding>${charset}</project.reporting.outputEncoding>
+		<project.build.sourceEncoding>${charset}</project.build.sourceEncoding>
+
+		<mainClass>org.spongepowered.docs.tools.codeblock.Main</mainClass>
+		<maven.build.timestamp.format>yyyy-MM-dd'T'HH:mm:ss'Z'</maven.build.timestamp.format>
+	</properties>
+
+	<repositories>
+		<repository>
+			<id>sponge</id>
+			<url>https://repo.spongepowered.org/maven</url>
+		</repository>
+	</repositories>
+
+	<dependencies>
+		<dependency>
+			<groupId>org.slf4j</groupId>
+			<artifactId>slf4j-api</artifactId>
+			<version>1.7.25</version>
+		</dependency>
+
+		<dependency>
+			<groupId>org.apache.logging.log4j</groupId>
+			<artifactId>log4j-slf4j-impl</artifactId>
+			<version>2.11.1</version>
+			<scope>runtime</scope>
+		</dependency>
+
+		<!-- Only needed for verifying the extracted code-blocks -->
+		<dependency>
+			<groupId>org.spongepowered</groupId>
+			<artifactId>spongeapi</artifactId>
+			<version>${sponge.api.version}</version>
+			<scope>provided</scope>
+		</dependency>
+
+		<!-- Test -->
+		<dependency>
+			<groupId>org.junit.jupiter</groupId>
+			<artifactId>junit-jupiter-engine</artifactId>
+			<version>5.3.1</version>
+			<scope>test</scope>
+		</dependency>
+
+	</dependencies>
+
+	<build>
+		<defaultGoal>clean package exec:java</defaultGoal>
+		<resources>
+			<resource>
+				<directory>.</directory>
+				<includes>
+					<include>LICENSE.txt</include>
+				</includes>
+			</resource>
+			<resource>
+				<directory>src/main/resources</directory>
+			</resource>
+		</resources>
+		<plugins>
+			<!-- Meta -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-enforcer-plugin</artifactId>
+				<version>3.0.0-M2</version>
+				<executions>
+					<execution>
+						<id>enforce-maven</id>
+						<goals>
+							<goal>enforce</goal>
+						</goals>
+						<configuration>
+							<rules>
+								<requireMavenVersion>
+									<version>3.5</version>
+								</requireMavenVersion>
+							</rules>
+						</configuration>
+					</execution>
+				</executions>
+			</plugin>
+			<plugin>
+				<groupId>org.codehaus.mojo</groupId>
+				<artifactId>versions-maven-plugin</artifactId>
+				<version>2.7</version>
+			</plugin>
+			<!-- Tests -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<version>2.22.1</version>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-failsafe-plugin</artifactId>
+				<version>2.22.1</version>
+			</plugin>
+			<!-- Packaging -->
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-jar-plugin</artifactId>
+				<version>3.1.0</version>
+				<configuration>
+					<archive>
+						<manifest>
+							<mainClass>${mainClass}</mainClass>
+							<addDefaultSpecificationEntries>true</addDefaultSpecificationEntries>
+							<addDefaultImplementationEntries>true</addDefaultImplementationEntries>
+						</manifest>
+						<manifestEntries>
+							<build-timestamp>${maven.build.timestamp}</build-timestamp>
+						</manifestEntries>
+					</archive>
+				</configuration>
+			</plugin>
+			<plugin>
+				<groupId>org.apache.maven.plugins</groupId>
+				<artifactId>maven-shade-plugin</artifactId>
+				<version>3.2.0</version>
+				<executions>
+					<!-- Create a jar that can be run standalone -->
+					<execution>
+						<id>package-standalone</id>
+						<phase>package</phase>
+						<goals>
+							<goal>shade</goal>
+						</goals>
+					</execution>
+				</executions>
+				<configuration>
+					<createDependencyReducedPom>false</createDependencyReducedPom>
+					<shadedArtifactAttached>true</shadedArtifactAttached>
+					<shadedClassifierName>standalone</shadedClassifierName>
+				</configuration>
+			</plugin>
+			<!-- Execution -->
+			<plugin>
+				<groupId>org.codehaus.mojo</groupId>
+				<artifactId>exec-maven-plugin</artifactId>
+				<version>1.6.0</version>
+				<configuration>
+					<mainClass>${mainClass}</mainClass>
+				</configuration>
+			</plugin>
+		</plugins>
+	</build>
+
+</project>