mirror of
https://github.com/pesde-pkg/pesde.git
synced 2024-12-12 11:00:36 +00:00
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
This commit is contained in:
Luka
GitHub
parent
1369fe990b
commit
f1c9cbc9fd
3 changed files with 291 additions and 34 deletions
|
|
@ -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"]
|
||||
```
|
||||
|
||||
<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.
|
||||
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
|
||||
}
|
||||
```
|
||||
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
<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>
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
<LinkCard
|
||||
title="Workspaces"
|
||||
description="Learn more about workspaces in pesde."
|
||||
href="/guides/workspaces/"
|
||||
title="Workspaces"
|
||||
description="Learn more about workspaces in pesde."
|
||||
href="/guides/workspaces/"
|
||||
/>
|
||||
|
||||
|
||||
## `[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.
|
||||
|
||||
<LinkCard
|
||||
title="Using Binary Packages"
|
||||
description="Learn more about using binary packages in pesde."
|
||||
href="/guides/binary-packages/"
|
||||
title="Using Binary Packages"
|
||||
description="Learn more about using binary packages in pesde."
|
||||
href="/guides/binary-packages/"
|
||||
/>
|
||||
|
||||
### `build_files`
|
||||
|
|
@ -183,15 +182,15 @@ You can find template scripts inside the
|
|||
for various sync tools.
|
||||
|
||||
<LinkCard
|
||||
title="Roblox"
|
||||
description="Learn more about using pesde in Roblox projects."
|
||||
href="/guides/roblox/"
|
||||
title="Roblox"
|
||||
description="Learn more about using pesde in Roblox projects."
|
||||
href="/guides/roblox/"
|
||||
/>
|
||||
|
||||
<LinkCard
|
||||
title="Example script 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"
|
||||
title="Example script 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"
|
||||
/>
|
||||
|
||||
### `sourcemap_generator`
|
||||
|
|
@ -204,9 +203,9 @@ The script will receive the path to the package directory as the first argument
|
|||
through `process.args`.
|
||||
|
||||
<LinkCard
|
||||
title="Example script 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"
|
||||
title="Example script 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"
|
||||
/>
|
||||
|
||||
## `[indices]`
|
||||
|
|
@ -270,9 +269,9 @@ refers to the `baz` dependency of the `bar` package, which is a dependency of
|
|||
the `foo` package.
|
||||
|
||||
<LinkCard
|
||||
title="Overrides"
|
||||
description="Learn more about overriding and patching packages."
|
||||
href="/guides/overrides/"
|
||||
title="Overrides"
|
||||
description="Learn more about overriding and patching packages."
|
||||
href="/guides/overrides/"
|
||||
/>
|
||||
|
||||
## `[patches]`
|
||||
|
|
@ -295,9 +294,9 @@ patch.
|
|||
The patches can be generated using the `pesde patch` command.
|
||||
|
||||
<LinkCard
|
||||
title="Overrides"
|
||||
description="Learn more about overriding and patching packages."
|
||||
href="/guides/overrides/"
|
||||
title="Overrides"
|
||||
description="Learn more about overriding and patching packages."
|
||||
href="/guides/overrides/"
|
||||
/>
|
||||
|
||||
## `[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`.
|
||||
|
||||
<LinkCard
|
||||
title="Workspaces"
|
||||
description="Learn more about workspace dependencies in pesde."
|
||||
href="/guides/workspaces/#workspace-dependencies"
|
||||
/>
|
||||
|
||||
## `[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" }
|
||||
```
|
||||
|
||||
<br/>
|
||||
<br />
|
||||
|
||||
<LinkCard
|
||||
title="Specifying Dependencies"
|
||||
description="Learn more about specifying dependencies in pesde."
|
||||
href="/guides/dependencies/"
|
||||
title="Specifying Dependencies"
|
||||
description="Learn more about specifying dependencies in pesde."
|
||||
href="/guides/dependencies/"
|
||||
/>
|
||||
|
|
|
|||
Loading…
Reference in a new issue