mirror of
https://github.com/pesde-pkg/pesde.git
synced 2024-12-13 11:50:36 +00:00
feat(website): add documentation
This commit is contained in:
daimond113
parent
f897d5bc4a
commit
a7947f6fbf
4 changed files with 252 additions and 1 deletions
|
|
@ -8,7 +8,7 @@
|
||||||
</script>
|
</script>
|
||||||
|
|
||||||
{#await codeToHtml(code, { theme: 'vesper', lang, transformers: [{ pre(node) {
|
{#await codeToHtml(code, { theme: 'vesper', lang, transformers: [{ pre(node) {
|
||||||
this.addClassToHast(node, 'not-prose');
|
this.addClassToHast(node, 'not-prose overflow-x-auto');
|
||||||
} }] }) then highlightedCode}
|
} }] }) then highlightedCode}
|
||||||
{@html highlightedCode}
|
{@html highlightedCode}
|
||||||
{/await}
|
{/await}
|
||||||
|
|
|
||||||
|
|
@ -74,6 +74,7 @@
|
||||||
>
|
>
|
||||||
<a href="https://github.com/daimond113/pesde" class="w-max">GitHub Repository</a>
|
<a href="https://github.com/daimond113/pesde" class="w-max">GitHub Repository</a>
|
||||||
<a href="/policies">Policies</a>
|
<a href="/policies">Policies</a>
|
||||||
|
<a href="/docs">Documentation</a>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
|
||||||
240
website/src/routes/docs/+page.svelte
Normal file
240
website/src/routes/docs/+page.svelte
Normal file
|
|
@ -0,0 +1,240 @@
|
||||||
|
<script lang="ts">
|
||||||
|
import Codeblock from '$lib/Codeblock.svelte';
|
||||||
|
import Note from './Note.svelte';
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<div class="max-w-prose">
|
||||||
|
<h1>Using pesde</h1>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Initializing a package</h2>
|
||||||
|
<p>
|
||||||
|
Even if you're not making a package, but something else such as a game, you will still need to
|
||||||
|
initialize package.
|
||||||
|
</p>
|
||||||
|
<Codeblock code="pesde init" />
|
||||||
|
<p>This will prompt you questions, after which it will create a pesde.yaml file.</p>
|
||||||
|
<Note>
|
||||||
|
If you are using pesde with the `wally` feature enabled (true on releases from the GitHub
|
||||||
|
repository) then you can use <Codeblock code="pesde convert" /> to convert your wally.toml file
|
||||||
|
to pesde.yaml. This will leave you with an empty default index, so you will need to add a URL (such
|
||||||
|
as the default `<a href="https://github.com/daimond113/pesde-index"
|
||||||
|
>https://github.com/daimond113/pesde-index</a
|
||||||
|
>`) yourself.
|
||||||
|
</Note>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Adding dependencies</h2>
|
||||||
|
<p>
|
||||||
|
You can use the `add` command to add dependencies to your project. With the `wally` feature
|
||||||
|
enabled, you can add Wally dependencies.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If you are making a package, you can use the `--peer` argument to add a package as a peer
|
||||||
|
dependency. Peer dependencies are not installed when the package is installed, but are
|
||||||
|
required to be installed by the user of the package. This is useful for things like framework
|
||||||
|
plugins.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
If you want to declare the dependency as server or development only, you can use the `--realm
|
||||||
|
server` or `--realm development` arguments respectively. The `shared` realm is the default.
|
||||||
|
</p>
|
||||||
|
<Codeblock
|
||||||
|
code="pesde add --realm server SCOPE/NAME@VERSION
|
||||||
|
pesde add --realm development wally#SCOPE/NAME@VERSION # for Wally packages"
|
||||||
|
/>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Overriding dependencies</h2>
|
||||||
|
<p>
|
||||||
|
Dependency overrides allow you to use a different version of a dependency than the one
|
||||||
|
specified in the package. This is useful for sharing 1 version of a dependency.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
Dependency overrides use the keys in the format of desired names separated with `>`, and
|
||||||
|
optionally other paths separated with `,`. The value is a dependency specifier.
|
||||||
|
</p>
|
||||||
|
<Note class="mb-4">
|
||||||
|
Dependency overrides do not have a command. You will need to edit the pesde.yaml file
|
||||||
|
yourself.
|
||||||
|
</Note>
|
||||||
|
<Codeblock
|
||||||
|
lang="yaml"
|
||||||
|
code="overrides:
|
||||||
|
DESIRED_NAME>DEPENDENCY_DESIRED_NAME,DESIRED_NAME_2>DEPENDENCY_DESIRED_NAME_2:
|
||||||
|
name: SCOPE/NAME
|
||||||
|
version: VERSION"
|
||||||
|
/>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Removing dependencies</h2>
|
||||||
|
<p>You can use the `remove` command to remove dependencies from your project.</p>
|
||||||
|
<Codeblock
|
||||||
|
code="pesde remove SCOPE/NAME@VERSION
|
||||||
|
pesde remove wally#SCOPE/NAME@VERSION"
|
||||||
|
/>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Outdated dependencies</h2>
|
||||||
|
<p>
|
||||||
|
You can list outdated dependencies with the `outdated` command. This will list all
|
||||||
|
dependencies that have a newer version available.
|
||||||
|
</p>
|
||||||
|
<Note class="mb-4">
|
||||||
|
This command only supports pesde registries, so neither Git nor Wally dependencies will be
|
||||||
|
listed.
|
||||||
|
</Note>
|
||||||
|
<Codeblock code="pesde outdated" />
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Installing a project</h2>
|
||||||
|
<p>The `install` command will install all dependencies of a project.</p>
|
||||||
|
<p>
|
||||||
|
You can use the `--locked` argument to skip resolving and read the dependencies from the
|
||||||
|
lockfile. If any changes were made from the time the lockfile was generated this will error.
|
||||||
|
</p>
|
||||||
|
<Codeblock code="pesde install" />
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Running a bin dependency</h2>
|
||||||
|
<p>
|
||||||
|
Dependencies may export a bin script. You can run this script with the `run` command. The
|
||||||
|
script will be executed with Lune. You can use the `--` argument to pass arguments to the
|
||||||
|
script.
|
||||||
|
</p>
|
||||||
|
<Note class="mb-4">
|
||||||
|
This does <b>not</b> support Wally dependencies.
|
||||||
|
</Note>
|
||||||
|
<Codeblock code="pesde run SCOPE/NAME -- -arg" />
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Patching dependencies</h2>
|
||||||
|
<p>
|
||||||
|
You can use the `patch` command to patch a dependency. This will output a directory in which
|
||||||
|
you can edit the dependency. After you are done, run the `patch-commit` command with the
|
||||||
|
directory as an argument to commit the changes.
|
||||||
|
</p>
|
||||||
|
<Codeblock
|
||||||
|
code="pesde patch SCOPE/NAME@VERSION
|
||||||
|
pesde patch-commit DIRECTORY"
|
||||||
|
/>
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Publishing a package</h2>
|
||||||
|
<p>
|
||||||
|
You can publish a package with the `publish` command. This will upload the package to the
|
||||||
|
registry. This will publish to the `default` index.
|
||||||
|
</p>
|
||||||
|
<Note class="mb-4"
|
||||||
|
>The official pesde registry does not support publishing packages with Wally or Git
|
||||||
|
dependencies. Dependency overrides and patches of your package as a dependency will be
|
||||||
|
ignored.</Note
|
||||||
|
>
|
||||||
|
<Codeblock code="pesde publish" />
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Searching for packages</h2>
|
||||||
|
<p>
|
||||||
|
You can search for packages with the `search` command. This will list all packages that match
|
||||||
|
the query. It will search by name and description.
|
||||||
|
</p>
|
||||||
|
<Codeblock code="pesde search QUERY" />
|
||||||
|
</section>
|
||||||
|
|
||||||
|
<section>
|
||||||
|
<h2>Manifest format cheat sheet</h2>
|
||||||
|
<p>
|
||||||
|
Here is a cheat sheet for the manifest format. This is the format of the pesde.yaml file. The
|
||||||
|
`name` and `version` fields are required. All other fields are optional.
|
||||||
|
</p>
|
||||||
|
<p>A description of each type:</p>
|
||||||
|
<ul>
|
||||||
|
<li>PACKAGE_NAME: either a STANDARD_PACKAGE_NAME or WALLY_PACKAGE_NAME</li>
|
||||||
|
<li>STANDARD_PACKAGE_NAME: refers to a package name used by pesde</li>
|
||||||
|
<li>
|
||||||
|
WALLY_PACKAGE_NAME: refers to a package name used by Wally. This will usually be prefixed
|
||||||
|
with `wally#`, although not required when this rather than `PACKAGE_NAME` is the type
|
||||||
|
</li>
|
||||||
|
<li>VERSION: a semver version specifier</li>
|
||||||
|
<li>VERSION_REQ: a semver version requirement</li>
|
||||||
|
<li>REALM: one of `shared`, `server`, or `development`</li>
|
||||||
|
<li>COMMAND: a command to run</li>
|
||||||
|
<li>
|
||||||
|
DEPENDENCY_SPECIFIER: one of REGISTRY_DEPENDENCY_SPECIFIER, GIT_DEPENDENCY_SPECIFIER,
|
||||||
|
WALLY_DEPENDENCY_SPECIFIER
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
REGISTRY_DEPENDENCY_SPECIFIER: an object with the following structure:
|
||||||
|
<Codeblock
|
||||||
|
lang="yaml"
|
||||||
|
code="name: STANDARD_PACKAGE_NAME
|
||||||
|
version: VERSION_REQ
|
||||||
|
# OPTIONAL (name in the `indices` field)
|
||||||
|
index: STRING"
|
||||||
|
/>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
GIT_DEPENDENCY_SPECIFIER: an object with the following structure:
|
||||||
|
<Codeblock
|
||||||
|
lang="yaml"
|
||||||
|
code="repo: URL
|
||||||
|
rev: STRING"
|
||||||
|
/>
|
||||||
|
</li>
|
||||||
|
<li>
|
||||||
|
WALLY_DEPENDENCY_SPECIFIER: an object with the following structure:
|
||||||
|
<Codeblock
|
||||||
|
lang="yaml"
|
||||||
|
code="wally: WALLY_PACKAGE_NAME
|
||||||
|
version: VERSION_REQ
|
||||||
|
index_url: URL"
|
||||||
|
/>
|
||||||
|
</li>
|
||||||
|
</ul>
|
||||||
|
<Codeblock
|
||||||
|
lang="yaml"
|
||||||
|
code="name: PACKAGE_NAME
|
||||||
|
version: VERSION
|
||||||
|
description: STRING
|
||||||
|
license: STRING
|
||||||
|
authors: STRING[]
|
||||||
|
repository: URL
|
||||||
|
exports:
|
||||||
|
lib: PATH
|
||||||
|
bin: PATH
|
||||||
|
path_style: !roblox
|
||||||
|
place: {
|
||||||
|
REALM: STRING
|
||||||
|
}
|
||||||
|
private: BOOL
|
||||||
|
realm: REALM
|
||||||
|
indices:
|
||||||
|
STRING: URL
|
||||||
|
# WALLY FEATURE ONLY
|
||||||
|
sourcemap_generator: COMMAND
|
||||||
|
overrides:
|
||||||
|
OVERRIDE_KEY: DEPENDENCY_SPECIFIER
|
||||||
|
|
||||||
|
dependencies: DEPENDENCY_SPECIFIER[]
|
||||||
|
peer_dependencies: DEPENDENCY_SPECIFIER[]"
|
||||||
|
/>
|
||||||
|
<p>
|
||||||
|
If the realm field is not specified, it will default to `shared`. If it is another value, and
|
||||||
|
the package is to be installed in a different realm, pesde will error.
|
||||||
|
</p>
|
||||||
|
<p>
|
||||||
|
The sourcemap generator command is only used for Wally and Git packages. It will be ran in a
|
||||||
|
package's directory, and must output a sourcemap file. This is used to generate a sourcemap
|
||||||
|
for the package so that types may be found and re-exported.
|
||||||
|
</p>
|
||||||
|
</section>
|
||||||
|
</div>
|
||||||
10
website/src/routes/docs/Note.svelte
Normal file
10
website/src/routes/docs/Note.svelte
Normal file
|
|
@ -0,0 +1,10 @@
|
||||||
|
<script lang="ts">
|
||||||
|
let className = '';
|
||||||
|
|
||||||
|
export { className as class };
|
||||||
|
</script>
|
||||||
|
|
||||||
|
<div class={'px-6 py-4 bg-paper-1-alt rounded-md ' + className}>
|
||||||
|
<div class="text-2xl font-bold">Note</div>
|
||||||
|
<slot />
|
||||||
|
</div>
|
||||||
Loading…
Reference in a new issue