From c7a1b5328cb14540544dd43f7a13b94ca3d7b794 Mon Sep 17 00:00:00 2001
From: LukaDev <47296785+lukadev-0@users.noreply.github.com>
Date: Sat, 2 Nov 2024 21:12:55 +0100
Subject: [PATCH] docs: improve docs for publishing roblox packages

---
 docs/src/content/docs/guides/publishing.mdx |  14 +-
 docs/src/content/docs/guides/roblox.mdx     | 196 +++++++++++++++++++-
 2 files changed, 205 insertions(+), 5 deletions(-)

diff --git a/docs/src/content/docs/guides/publishing.mdx b/docs/src/content/docs/guides/publishing.mdx
index e111f31..51e62ce 100644
--- a/docs/src/content/docs/guides/publishing.mdx
+++ b/docs/src/content/docs/guides/publishing.mdx
@@ -3,6 +3,8 @@ title: Publishing Packages
 description: Learn how to publish packages to the pesde registry.
 ---
 
+import { LinkCard } from "@astrojs/starlight/components"
+
 ## Configuration
 
 Before you can publish a package, you must configure the required fields in your
@@ -41,15 +43,19 @@ lib = "init.luau"
 `build_files`. These are the files that should be synced into Roblox. They are
 passed to the `roblox_sync_config_generator` script.
 
-For more information, see [Roblox](/guides/roblox).
-
 ```toml
 [target]
 environment = "roblox"
-lib = "init.luau"
-build_files = ["init.luau"]
+lib = "src/init.luau"
+build_files = ["src"]
 ```
 
+<LinkCard
+	title="Roblox"
+	description="Learn more about authoring packages for Roblox."
+	href="/guides/roblox/#authoring-packages"
+/>
+
 ## Authentication
 
 Before you can publish a package, you must authenticate with your GitHub account.
diff --git a/docs/src/content/docs/guides/roblox.mdx b/docs/src/content/docs/guides/roblox.mdx
index b35517e..5994baa 100644
--- a/docs/src/content/docs/guides/roblox.mdx
+++ b/docs/src/content/docs/guides/roblox.mdx
@@ -3,6 +3,8 @@ title: Roblox
 description: Using pesde in a Roblox project.
 ---
 
+import { FileTree } from "@astrojs/starlight/components"
+
 pesde can be used in Roblox projects, however this requires some extra setup.
 Namely, you need to specify a `roblox_sync_config_generator` script in order
 to generate the adequate configuration for the sync tool you are using.
@@ -29,8 +31,200 @@ needed to use pesde in a project using Rojo.
 If you are using a different sync tool, you should look for it's scripts in the
 pesde-scripts repository. If you cannot find them, you can write your own and
 optionally submit a PR to help others using the same tool as you get started
-quicker. 
+quicker.
 
 Scaffold your project with `pesde init`, select the `roblox` or `roblox_server`
 target, and then replace the `.pesde/roblox_sync_config_generator.luau` script
 with the one you want to use.
+
+## Authoring packages
+
+When authoring packages for Roblox, it is recommended to have your code inside
+of a `src` directory (or any other directory you prefer).
+
+Inside of your `pesde.toml` you must specify the `roblox` environment and the
+`lib` field with the path to your main script. You must also specify a list of
+`build_files`. This list should contain names of top level files or directories
+that should be synced into Roblox by a sync tool, such as Rojo.
+
+Let's say you have a package with the following structure:
+
+<FileTree>
+
+- roblox_packages/
+  - dependency.luau
+  - ...
+- src/
+  - init.luau
+  - foo.luau
+  - bar.luau
+  - ...
+- LICENSE
+- pesde.toml
+- README.md
+- selene.toml
+- stylua.toml
+
+</FileTree>
+
+There are lots of files in the root directory that are not needed in Roblox,
+such as configuration files, READMEs, and licenses. We only want the `src` and
+the `roblox_packages` directory to be synced into Roblox.
+
+<FileTree>
+
+- roblox_packages/
+  - dependency (roblox_packages/dependency.luau)
+  - ...
+- src/ (src/init.luau)
+  - foo (src/foo.luau)
+  - bar (src/bar.luau)
+  - ...
+
+</FileTree>
+
+This is where `build_files` come in, we can specify a list of files that should
+be synced into Roblox. In this case, we only want the `src` directory to be
+synced. We do not need to specify the `roblox_packages` directory, as it is
+always synced.
+
+So for our package, the `pesde.toml` file would roughly look like this:
+
+```toml title="pesde.toml" {15}
+name = "acme/package"
+version = "1.0.0"
+license = "MIT"
+
+includes = [
+  "pesde.toml",
+  "LICENSE",
+  "README.md",
+  "src",
+]
+
+[target]
+environment = "roblox"
+lib = "src/init.luau"
+build_files = ["src"]
+
+[dependencies]
+dependency = "acme/library"
+```
+
+When a consumer of your package installs it, the `roblox_sync_config_generator`
+script they are using will generate the configuration needed for their sync
+tool. For example, a Rojo user would get a `default.project.json` with the
+following contents:
+
+```json title="default.project.json"
+{
+	"tree": {
+		"src": {
+			"$path": "src"
+		},
+		"roblox_packages": {
+			"$path": "roblox_packages"
+		}
+	}
+}
+```
+
+The linker scripts that pesde generates will then point to the `src` module.
+
+Then, to publish your package, you can follow the steps in the
+["Publishing Packages"](/guides/publishing/) guide.
+
+### Test place with Rojo
+
+You might want to create a "test place" where you can test your package inside
+Roblox, or to get proper LSP support when developing your package.
+
+To do this, you can create a `test-place.project.json` file which includes your
+package and the `roblox_packages` directory.
+
+```json title="test-place.project.json"
+{
+	"tree": {
+		"$className": "DataModel",
+		"ReplicatedStorage": {
+			"package": {
+				"$className": "Folder",
+				"src": {
+					"$path": "src"
+				},
+				"roblox_packages": {
+					"$path": "roblox_packages"
+				}
+			}
+		}
+	}
+}
+```
+
+You can then run `rojo serve` with this project file:
+
+```sh
+rojo serve test-place.project.json
+```
+
+If you are using [Luau LSP](https://github.com/JohnnyMorganz/luau-lsp) you can
+change the `luau-lsp.sourcemap.rojoProjectFile` extension setting to
+`test-place.project.json` to get proper LSP support when developing your
+package.
+
+### Differences from Wally
+
+Those coming from [Wally](https://wally.run/) may be a bit confused by the
+way pesde handles Roblox packages.
+
+In Wally, it is standard to have a `default.project.json` with the following:
+
+```json
+{
+	"tree": {
+		"$path": "src"
+	}
+}
+```
+
+This will cause the `src` directory to be directly synced into Roblox.
+
+In pesde, you should not have a `default.project.json` file in your package.
+Instead, you use the `build_files` field to specify what should be synced. This
+allows the consumer of your package to choose the sync tool they want to use,
+instead of being constrained to only using Rojo.
+
+This has the effect that the structure of the files in the file system ends up
+being reflected inside Roblox.
+
+With Wally, the structure that ends up in Roblox ends up looking like this:
+
+<FileTree>
+
+- Packages/
+  - \_Index/
+    - acme_package@1.0.0/
+      - package/ (src/init.luau)
+        - foo (src/foo.luau)
+        - bar (src/bar.luau)
+        - ...
+      - dependency
+
+</FileTree>
+
+Whereas with pesde, it looks like this:
+
+<FileTree>
+
+- roblox_packages/
+  - .pesde/
+    - acme+package/
+      - 1.0.0/
+        - src/ (src/init.luau)
+          - foo (src/foo.luau)
+          - bar (src/bar.luau)
+          - ...
+        - roblox_packages/
+          - dependency (roblox_packages/dependency.luau)
+
+</FileTree>