pesde-pkg/pesde
1
1
Fork 0
mirror of https://github.com/pesde-pkg/pesde.git synced 2024-12-12 11:00:36 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

docs: documentation improvements (#6)

Browse source 
* docs: improve docs for publishing roblox packages

* docs: add workspace dependencies to reference

* docs: reword roblox publishing docs

* docs: improve documentation for package docs
This commit is contained in:
Luka 2024-11-11 12:45:41 +01:00 committed by GitHub
parent 1369fe990b
commit f1c9cbc9fd
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 291 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

57
docs/src/content/docs/guides/publishing.mdx
View file

@ -3,6 +3,8 @@ title: Publishing Packages
description: Learn how to publish packages to the pesde registry. description: Learn how to publish packages to the pesde registry.
--- ---
import { Aside, LinkCard } from "@astrojs/starlight/components"
## Configuration ## Configuration
Before you can publish a package, you must configure the required fields in your 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 `build_files`. These are the files that should be synced into Roblox. They are
passed to the `roblox_sync_config_generator` script. passed to the `roblox_sync_config_generator` script.
For more information, see [Roblox](/guides/roblox).
```toml ```toml
[target] [target]
environment = "roblox" environment = "roblox"
lib = "init.luau" lib = "src/init.luau"
build_files = ["init.luau"] build_files = ["src"]
``` ```
<LinkCard
title="Roblox"
description="Learn more about authoring packages for Roblox."
href="/guides/roblox/#authoring-packages"
/>
## Authentication ## 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 ```sh
pesde auth login pesde auth login
@ -90,5 +97,41 @@ environment.
The `README.md` file in the root of the package will be displayed on the The `README.md` file in the root of the package will be displayed on the
[pesde registry website](https://pesde.daimond113.com/). [pesde registry website](https://pesde.daimond113.com/).
If you have a `docs` directory in the root of the package, they will be You can include a `docs` directory in the package containing markdown files
hosted by pesde and be accessible on the pesde website. 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
}
```
<Aside type="tip">
Make sure to include `docs` inside the `includes` field in `pesde.toml`
otherwise they won't be published with your package.
</Aside>

198
docs/src/content/docs/guides/roblox.mdx
View file

@ -3,6 +3,8 @@ title: Roblox
description: Using pesde in a Roblox project. 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. 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 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. 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 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 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 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` Scaffold your project with `pesde init`, select the `roblox` or `roblox_server`
target, and then replace the `.pesde/roblox_sync_config_generator.luau` script target, and then replace the `.pesde/roblox_sync_config_generator.luau` script
with the one you want to use. 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 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:
<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>

70
docs/src/content/docs/reference/manifest.mdx
View file

@ -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. A list of globs containing the members of this workspace.
<LinkCard <LinkCard
title="Workspaces" title="Workspaces"
description="Learn more about workspaces in pesde." description="Learn more about workspaces in pesde."
href="/guides/workspaces/" href="/guides/workspaces/"
/> />
## `[target]` ## `[target]`
The `[target]` section contains information about the target platform for the 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. run when the package is executed as a binary.
<LinkCard <LinkCard
title="Using Binary Packages" title="Using Binary Packages"
description="Learn more about using binary packages in pesde." description="Learn more about using binary packages in pesde."
href="/guides/binary-packages/" href="/guides/binary-packages/"
/> />
### `build_files` ### `build_files`
@ -183,15 +182,15 @@ You can find template scripts inside the
for various sync tools. for various sync tools.
<LinkCard <LinkCard
title="Roblox" title="Roblox"
description="Learn more about using pesde in Roblox projects." description="Learn more about using pesde in Roblox projects."
href="/guides/roblox/" href="/guides/roblox/"
/> />
<LinkCard <LinkCard
title="Example script for Rojo" title="Example script for Rojo"
description="An example script for generating configuration for Rojo." description="An example script for generating configuration for Rojo."
href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/roblox_sync_config_generator.luau" href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/roblox_sync_config_generator.luau"
/> />
### `sourcemap_generator` ### `sourcemap_generator`
@ -204,9 +203,9 @@ The script will receive the path to the package directory as the first argument
through `process.args`. through `process.args`.
<LinkCard <LinkCard
title="Example script for Rojo" title="Example script for Rojo"
description="An example script for generating configuration for Rojo." description="An example script for generating configuration for Rojo."
href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/sourcemap_generator.luau" href="https://github.com/daimond113/pesde-scripts/blob/master/lune/rojo/sourcemap_generator.luau"
/> />
## `[indices]` ## `[indices]`
@ -270,9 +269,9 @@ refers to the `baz` dependency of the `bar` package, which is a dependency of
the `foo` package. the `foo` package.
<LinkCard <LinkCard
title="Overrides" title="Overrides"
description="Learn more about overriding and patching packages." description="Learn more about overriding and patching packages."
href="/guides/overrides/" href="/guides/overrides/"
/> />
## `[patches]` ## `[patches]`
@ -295,9 +294,9 @@ patch.
The patches can be generated using the `pesde patch` command. The patches can be generated using the `pesde patch` command.
<LinkCard <LinkCard
title="Overrides" title="Overrides"
description="Learn more about overriding and patching packages." description="Learn more about overriding and patching packages."
href="/guides/overrides/" href="/guides/overrides/"
/> />
## `[place]` ## `[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 - `path`: The path within the repository to install. If not specified, the root
of the repository is used. 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`.
<LinkCard
title="Workspaces"
description="Learn more about workspace dependencies in pesde."
href="/guides/workspaces/#workspace-dependencies"
/>
## `[peer_dependencies]` ## `[peer_dependencies]`
The `[peer_dependencies]` section contains a list of peer dependencies for the 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" } foo = { name = "acme/foo", version = "1.2.3" }
``` ```
<br/> <br />
<LinkCard <LinkCard
title="Specifying Dependencies" title="Specifying Dependencies"
description="Learn more about specifying dependencies in pesde." description="Learn more about specifying dependencies in pesde."
href="/guides/dependencies/" href="/guides/dependencies/"
/> />