Add basic "documentation"

.gitlab-ci.yml

@@ -1,2 +1,14 @@
 include:
   - remote: 'https://jfmods.gitlab.io/scripts/jfmod.yml'
+
+pages:
+  image: python:3.8-buster
+  stage: deploy
+  script:
+    - pip install mkdocs
+    - mkdocs build
+  artifacts:
+    paths:
+      - public
+  only:
+    - master

docs/README.md

@@ -0,0 +1,36 @@
+# About
+LibJF is split into several modules, each of which provides separate functionality.
+This modularization is inspired by Fabric API.
+LibJF is only maintained for the latest version of minecraft and tries to provide a stable ABI during its lifespan
+but is open for breaking changes between versions.
+
+Be aware that modules may depend on another and maven builds do not include dependencies.
+Modules may also require fabric-api to be present to work properly
+
+### Using LibJF
+The recommended way to use LibJF is using the JfMods scripts, which include the LibJF maven repository
+and simplify building fabric mods. My own mods (including LibJF) use these.
+
+Otherwise you can add the repository as follows:
+```groovy
+repositories {
+    maven { url 'https://gitlab.com/api/v4/projects/25805200/packages/maven' }
+}
+```
+and include LibJF modules like this:
+```groovy
+dependencies {
+    include modImplementation("io.gitlab.jfronny.libjf:libjf-config-v0:${project.jfapi_version}")
+    include("io.gitlab.jfronny.libjf:libjf-unsafe-v0:${project.jfapi_version}")
+    include("io.gitlab.jfronny.libjf:libjf-base:${project.jfapi_version}")
+    modRuntimeOnly("io.gitlab.jfronny.libjf:libjf-devutil-v0:${project.jfapi_version}")
+}
+```
+
+For more information on specific modules, you can look at their own pages
+
+### Developing LibJF
+To add a LibJF module, create a new directory for it and copy over a build.gradle file from elsewhere,
+Reference it in settings.gradle and develop it like any fabric mod.
+You should also create a testmod for it (look at the other modules for examples)
+JiJing and maven uploads are automatically managed by the JfMods scripts

docs/libjf-base.md

@@ -0,0 +1,13 @@
+# libjf-base
+libjf-base is a dependency of all other modules and provides common functionality between them.
+It has no dependencies.
+It includes:
+
+- a Gson strategy to ignore fields annotated with GsonHidden
+- LazySupplier, a supplier that caches the result of another supplier to which it delegates
+- ThrowingRunnable and ThrowingSupplier, counterparts of their default lambdas which allow exceptions
+- a "flags" system to allow dynamically enabling LibJF features through system properties and fabric.mod.jsons
+- a shared logger and Gson instance
+- the ResourcePath abstraction to describe locations of resources as simple strings
+
+All of these are implemented in one reusable class (except the Gson strategy, whose annotation is separate), which should be simple to read

docs/libjf-config-v0.md

@@ -0,0 +1,38 @@
+# libjf-config-v0
+LibJF config provides config screens and is partially based on TinyConfig and MidnightLib
+It depends on libjf-unsafe-v0 to ensure configs are loaded before you use them and libjf-base
+To add a config create a class using only static fields with default values like this:
+```java
+import io.gitlab.jfronny.libjf.config.api.JfConfig;
+import io.gitlab.jfronny.libjf.config.api.Entry;
+import io.gitlab.jfronny.libjf.gson.GsonHidden;
+
+public class TestConfig implements JfConfig {
+    @Entry public static boolean disablePacks = false;
+    @Entry public static Boolean disablePacks2 = false;
+    @Entry public static int intTest = 20;
+    @Entry(min = -6) public static float floatTest = -5;
+    @Entry(max = 21) public static double doubleTest = 20;
+    @Entry public static String dieStr = "lolz";
+    @Entry @GsonHidden public static String guiOnlyStr = "lolz";
+    public static String gsonOnlyStr = "lolz";
+    @Entry public static Test enumTest = Test.Test;
+
+    public enum Test {
+        Test, ER
+    }
+}
+```
+You MUST annotate any field configurable through the UI as @Entry and the class MUST extend JfConfig.
+You MAY annotate fields as @GsonHidden to not serialize them (-> [libjf-base](libjf-base.md)).
+Numeric values MAY have a min and max value specified in their @Entry.
+
+To register a config, add a `libjf:config` entrypoint pointing to its class to your fabric.mod.json.
+To manually register a config or save changes, use `io.gitlab.jfronny.libjf.config.api.ConfigHolder`
+For example, to save a config for a mod titled `yourmod`:
+```java
+ConfigHolder.getInstance().getRegistered().get("yourmod").write();
+```
+
+LibJF config is only intended for simple config screens, it does not support nested classes, multiple pages or controls like sliders.
+Use something else for those

docs/libjf-data-manipulation-v0.md

@@ -0,0 +1,37 @@
+# libjf-data-manipulation-v0
+libjf-data-manipulation-v0 provides code for modifying existing resources.
+It depends on libjf-unsafe-v0 to patch ResourcePack implementations, libjf-base and fabric-api-base
+
+### RecipeUtil
+RecipeUtil provides to methods to end users:
+
+- `removeRecipe` blocks minecraft from loading recipes using the specified tag
+- `removeRecipeFor` blocks minecraft from loading recipes producing the specified output. (Look at the log to find out which ones it blocks)
+
+### UserResourceEvents
+UserResourceEvents provides four events (CONTAINS, FIND_RESOURCE, OPEN, OPEN_ROOT) which get called every time
+the corresponding method is called on and ResourcePack. They allow modifying the resulting data.
+This is used in respackopts to manipulate resource loading.
+To temporarily disable these hooks, call the "disable" function, which invokes the lambda it is passed and disables the hooks
+while it is running
+
+### Examples
+```java
+@Override
+public void onInitialize() {
+    // This should prevent resource packs from doing anything if my hooks are working and
+    UserResourceEvents.OPEN.register((type, id, previous, pack) -> {
+        if (pack instanceof DirectoryResourcePack) {
+            LibJf.LOGGER.info(pack.getName() + " opened " + type.name() + "/" + id.toString());
+        }
+        return previous.get();
+    });
+    UserResourceEvents.CONTAINS.register((type, id, previous, pack) -> {
+        if (pack instanceof DirectoryResourcePack) {
+            return false;
+        }
+        return previous.get();
+    });
+    RecipeUtil.removeRecipeFor(Items.DIAMOND_SWORD);
+}
+```

docs/libjf-data-v0.md

@@ -0,0 +1,7 @@
+# libjf-data-v0
+libjf-data-v0 provides two additional tags for use in other mods or datapacks:
+
+- `libjf:shulker_boxes_illegal` prevents items from being placed in shulker boxes (intended for backpacks)
+- `libjf:overpowered` makes entities wearing four or more armor items with this tag invincible
+
+It depends on libjf-base, fabric-tag-extensions-v0 and fabric-resource-loader-v0

docs/libjf-devutil-v0.md

@@ -0,0 +1,6 @@
+# libjf-devutil-v0
+LibJF devutil is intended to be used as `runtimeOnly`.
+It marks the running minecraft instance as a development instance and disables the UserApi (removing that Yggdrasil error message)
+It does not provide any useful functionality to end users
+
+It depends on libjf-base

docs/libjf-unsafe-v0.md

@@ -0,0 +1,40 @@
+# libjf-unsafe-v0
+libjf-unsafe-v0 provides an entrypoint which is called extremely early and ASM modification.
+It also ensures dependency libraries are on the classpath during both.
+libjf-unsafe-v0 only depends on libjf-base, though using it with the fabric loader version it was developed for is recommended
+
+### UltraEarlyInit
+Implement `UltraEarlyInit` on your entrypoint and add it as a `libjf:early` entrypoint
+Please be aware that using any non-jdk classes during the ultra early init stage prevents them from being modified by Mixin/ASM.
+
+### ASM
+Implement `AsmConfig` on a class and add it to your fabric.mod.json as a `libjf:asm` entrypoint.
+Use skipClasses to prevent a class from being modified by any ASM patches.
+getPatches should return a Set of patches that should be applied to classes (more on that later).
+skipClasses and getPatches will only be called once during the initialization process.
+Please be aware that using un-excluded classes during ASM modification can cause infinite loops.
+Please also note that during runtime, class names may be in intermediary, yarn or other mappings.
+You can use AsmTransformer.MAPPING_RESOLVER to resolve intermediary names to their runtime counterparts
+
+### Creating an ASM patch
+The current ClassNode will be passed to the apply method of every registered Patch instance.
+You may modify it as you like, but some default things are provided to make this easier:
+- InterfaceImplTargetPatch will apply a Patch only on classes implementing or extending the interface or class specified as the first parameter
+- MethodModificationPatch allows applying MethodPatches only to specific methods on specific classes
+- MethodReplacementPatch is a MethodPatch which replaces the content of its target method with a predefined InsnList
+
+Of course, you can (and should) implement your own patches in addition to these,
+Examples can be found in libjf-data-manipulation-v0 and GWWHIT
+
+### Debugging ASM
+Debugging ASM is difficult, but you can use the asm.log/asm.export flags to get additional output.
+You can do so either by adding `-Plibjf.asm.log -Plibjf.asm.export` to your JVM args or the following to your fabric.mod.json:
+```json
+"custom": {
+    "libjf": {
+        "asm.log": true,
+        "asm.export": true
+    }
+  }
+```
+I also recommend using IDEAs bytecode viewer on resulting classes to understand the bytecode

docs/libjf-web-v0.md

@@ -0,0 +1,17 @@
+# libjf-web-v0
+libjf-web-v0 provides a HTTP web server you can use in your serverside (and technically also clientside) mods
+to serve web content through a unified port.
+libjf-web-v0 depends on libjf-config-v0 to provide its config, libjf-base, fabric-lifecycle-events-v1 and fabric-command-api-v1
+
+### Getting started
+Implement WebInit and register it as a libjf:web entrypoint. To enable the server, also add the following to your fabric.mod.json:
+```json
+"custom": {
+    "libjf": {
+      "web": true
+    }
+  }
+```
+Please be aware that your entrypoint may be called multiple times during one session.
+You can register content providers using the register* methods on the WebServer parameter of your entrypoint.
+Please do not store it in a field, you may instead use WebServer.getInstance() if you wish to access it elsewhere.

libjf-unsafe-v0/src/main/java/io/gitlab/jfronny/libjf/unsafe/asm/patch/modification/MethodModificationPatch.java

@@ -36,7 +36,7 @@ public class MethodModificationPatch implements Patch {
         }
     }
 
-    public static record MethodDescriptorPatch(String methodName, String methodDescriptor, MethodPatch patch) {
+    public record MethodDescriptorPatch(String methodName, String methodDescriptor, MethodPatch patch) {
 
     }
 }

mkdocs.yml

@@ -0,0 +1,18 @@
+site_name: LibJF Docs
+site_url: https://jfmods.gitlab.io/LibJF
+theme:
+  name: readthedocs
+site_dir: public
+repo_url: https://gitlab.com/jfmods/LibJF
+site_description: Documentation for the LibJF library
+site_author: JFronny
+nav:
+  - 'README.md'
+  - 'Modules':
+      - 'libjf-base.md'
+      - 'libjf-config-v0.md'
+      - 'libjf-devutil-v0.md'
+      - 'libjf-data-v0.md'
+      - 'libjf-data-manipulation-v0.md'
+      - 'libjf-unsafe-v0.md'
+      - 'libjf-web-v0.md'