add readme

tools/Docgen/README.md

@@ -0,0 +1,45 @@
+# Docgen User Guide
+
+This guide details what Docgen is and how to use it.
+
+## What is Docgen
+
+Docgen is a tool that takes C# source code and generates Improbadoc compliant API documentation. The intended target of this tool is the GDK for Unity, but there are applications for it elsewhere (C# Worker SDK for example).
+
+There is also the possibility of generating API documentation for other languages like: C, C++, and Java as Docgen uses Doxygen as its backend for parsing the source code.
+
+## How to use Docgen
+
+### Prerequisites
+
+1. Be on Windows
+    - Currently the version of Doxygen that Docgen uses is custom built. Its based on 1.8.14 with https://github.com/doxygen/doxygen/pull/645 patched in for C# nullable support.
+    - This means that the person who wrote Docgen didn't want to bother building Doxygen from source for other platforms.
+
+Using Docgen is very simple. You just need to provide it with a few command line arguments.
+
+An example invocation would be:
+
+```bash
+dotnet run -p Docgen.csproj -- \
+--target-directory=../../../core/gdk-for-unity/workers/unity/Packages/ \
+--output-directory=../../../core/docs/docs/content/api \
+--target-namespace=Improbable.Gdk \
+--api-path=content/api \
+--namespace-filter=".*EditmodeTests" \
+--namespace-filter=".*PlaymodeTests" \
+```
+
+### Arguments
+
+#### Required
+
+- `--target-directory=` : This points to the source code that you wish to build docs for. Note that this is a relative path.
+- `--output-directory=` : This points to the output directory for the API documentation.
+- `--target-namespace=` : This defines the C# namespace to generate docs for. Any types outside of this namespace will be ignored.
+- `--api-path=` : This defines the path from the root of your docs folder to the location of the API documentation.
+
+#### Optional
+
+- `--namespace-filter=` : This is a regex which is used to filter **out** types and namespaces. Anything which has a fully qualified name which matches one of these regexes will be ignored.
+- `--keep-xml` : This is a useful debugging option which will not clean up the Doxygen XML so that you can inspect it.