From f1c9cbc9fd2e60907af1bfb804ea6a2968429916 Mon Sep 17 00:00:00 2001
From: Luka <47296785+lukadev-0@users.noreply.github.com>
Date: Mon, 11 Nov 2024 12:45:41 +0100
Subject: [PATCH] docs: documentation improvements (#6)
* docs: improve docs for publishing roblox packages
* docs: add workspace dependencies to reference
* docs: reword roblox publishing docs
* docs: improve documentation for package docs
---
docs/src/content/docs/guides/publishing.mdx | 57 +++++-
docs/src/content/docs/guides/roblox.mdx | 198 ++++++++++++++++++-
docs/src/content/docs/reference/manifest.mdx | 70 ++++---
3 files changed, 291 insertions(+), 34 deletions(-)
diff --git a/docs/src/content/docs/guides/publishing.mdx b/docs/src/content/docs/guides/publishing.mdx
index e111f31..309ff5d 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 { Aside, LinkCard } from "@astrojs/starlight/components"
+
## Configuration
Before you can publish a package, you must configure the required fields in your
@@ -41,18 +43,23 @@ 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"]
```
+
+
## Authentication
-Before you can publish a package, you must authenticate with your GitHub account.
+Before you can publish a package, you must authenticate with your GitHub
+account.
```sh
pesde auth login
@@ -90,5 +97,41 @@ environment.
The `README.md` file in the root of the package will be displayed on the
[pesde registry website](https://pesde.daimond113.com/).
-If you have a `docs` directory in the root of the package, they will be
-hosted by pesde and be accessible on the pesde website.
+You can include a `docs` directory in the package containing markdown files
+and they will be available on the pesde registry website. You can see an example
+in [`pesde/hello`](https://pesde.daimond113.com/packages/pesde/hello/latest/any/docs).
+
+### Customizing the sidebar
+
+You can include frontmatter with a `sidebar_position` to customize the order
+of the pages on the sidebar.
+
+```md title="docs/getting-started.md"
+---
+sidebar_position: 2
+---
+
+# Getting Started
+
+Lorem ipsum odor amet, consectetuer adipiscing elit. Eleifend consectetur id
+consequat conubia fames curae?
+```
+
+You can have directories in the `docs` directory to create nested pages. These
+will show up as collapsible sections in the sidebar. You can include a
+`_category_.json` file inside the nested directories to customize the label and
+the ordering in the sidebar.
+
+```json title="docs/guides/_category_.json"
+{
+ "label": "Guides",
+ "position": 3
+}
+```
+
+
diff --git a/docs/src/content/docs/guides/roblox.mdx b/docs/src/content/docs/guides/roblox.mdx
index b35517e..d9723e3 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,202 @@ 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:
+
+
+
+- roblox_packages/
+ - dependency.luau
+ - ...
+- src/
+ - init.luau
+ - foo.luau
+ - bar.luau
+ - ...
+- LICENSE
+- pesde.toml
+- README.md
+- selene.toml
+- stylua.toml
+
+
+
+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.
+
+
+
+- roblox_packages/
+ - dependency (roblox_packages/dependency.luau)
+ - ...
+- src/ (src/init.luau)
+ - foo (src/foo.luau)
+ - bar (src/bar.luau)
+ - ...
+
+
+
+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 are required to use the `build_files` field to specify a 1:1 match
+between Roblox and the file system. pesde forbids `default.project.json` to be
+part of a published package, and regenerates it when installing a pesde git
+dependency. 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:
+
+
+
+- Packages/
+ - \_Index/
+ - acme_package@1.0.0/
+ - package/ (src/init.luau)
+ - foo (src/foo.luau)
+ - bar (src/bar.luau)
+ - ...
+ - dependency
+
+
+
+Whereas with pesde, it looks like this:
+
+
+
+- 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)
+
+
diff --git a/docs/src/content/docs/reference/manifest.mdx b/docs/src/content/docs/reference/manifest.mdx
index c9abb9d..3bc7d89 100644
--- a/docs/src/content/docs/reference/manifest.mdx
+++ b/docs/src/content/docs/reference/manifest.mdx
@@ -94,12 +94,11 @@ this field and run the correct version of pesde for this project.
A list of globs containing the members of this workspace.
-
## `[target]`
The `[target]` section contains information about the target platform for the
@@ -135,9 +134,9 @@ The entry point of the binary exported by the package. This file is what will be
run when the package is executed as a binary.
### `build_files`
@@ -183,15 +182,15 @@ You can find template scripts inside the
for various sync tools.
### `sourcemap_generator`
@@ -204,9 +203,9 @@ The script will receive the path to the package directory as the first argument
through `process.args`.
## `[indices]`
@@ -270,9 +269,9 @@ refers to the `baz` dependency of the `bar` package, which is a dependency of
the `foo` package.
## `[patches]`
@@ -295,9 +294,9 @@ patch.
The patches can be generated using the `pesde patch` command.
## `[place]`
@@ -372,6 +371,25 @@ foo = { repo = "acme/packages", rev = "main", path = "foo" }
- `path`: The path within the repository to install. If not specified, the root
of the repository is used.
+### Workspace
+
+```toml
+[dependencies]
+foo = { workspace = "acme/foo", version = "^" }
+```
+
+**Workspace dependencies** contain the following fields:
+
+- `workspace`: The name of the package in the workspace.
+- `version`: The version requirement for the package. This can be `^`, `*`, `=`,
+ `~`, or a specific version requirement such as `^1.2.3`.
+
+
+
## `[peer_dependencies]`
The `[peer_dependencies]` section contains a list of peer dependencies for the
@@ -396,10 +414,10 @@ package is used by another package.
foo = { name = "acme/foo", version = "1.2.3" }
```
-
+