From a3eb2cddc35a58d42ed468f8a5806597f709345e Mon Sep 17 00:00:00 2001 From: Marcus Date: Sun, 28 Jul 2024 03:06:09 +0200 Subject: [PATCH] Improve docs (#90) * Add method * Remove unnecessary shadowed variable * Separate pages --- docs/.vitepress/config.mts | 110 ++++----- docs/concepts/queries.md | 3 - docs/concepts/static-components.md | 3 - docs/faq/contributing.md | 3 - docs/{ => learn}/concepts/entities.md | 2 +- docs/learn/concepts/queries.md | 3 + docs/learn/concepts/static-components.md | 3 + docs/learn/faq/contributing.md | 3 + docs/learn/overview/first-jecs-project.md | 3 + docs/{ => learn}/overview/get-started.md | 260 +++++++++++----------- docs/{ => learn}/overview/rbxm.png | Bin docs/{ => learn}/public/jecs_logo.svg | 0 docs/overview/first-jecs-project.md | 3 - 13 files changed, 203 insertions(+), 193 deletions(-) delete mode 100644 docs/concepts/queries.md delete mode 100644 docs/concepts/static-components.md delete mode 100644 docs/faq/contributing.md rename docs/{ => learn}/concepts/entities.md (50%) create mode 100644 docs/learn/concepts/queries.md create mode 100644 docs/learn/concepts/static-components.md create mode 100644 docs/learn/faq/contributing.md create mode 100644 docs/learn/overview/first-jecs-project.md rename docs/{ => learn}/overview/get-started.md (95%) rename docs/{ => learn}/overview/rbxm.png (100%) rename docs/{ => learn}/public/jecs_logo.svg (100%) delete mode 100644 docs/overview/first-jecs-project.md diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index a184354..f45a569 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -2,56 +2,66 @@ import { defineConfig } from 'vitepress' // https://vitepress.dev/reference/site-config export default defineConfig({ - title: "Jecs", - base: "/jecs/", - description: "A VitePress Site", - themeConfig: { - // https://vitepress.dev/reference/default-theme-config - nav: [ - { text: 'Home', link: '/' }, - { text: 'Examples', link: '/markdown-examples' } - ], + title: "Jecs", + base: "/jecs/", + description: "A VitePress Site", + themeConfig: { + // https://vitepress.dev/reference/default-theme-config + nav: [ + { text: 'Home', link: '/' }, + { text: 'Examples', link: '/markdown-examples' }, + { text: 'API', link: '/api/jecs.md' } + ], - sidebar: [ - { - text: 'Overview', - items: [ - { text: 'Getting Started', link: '/overview/get-started' }, - { text: 'First Jecs Project', link: '/overview/first-jecs-project' } - ] - }, - { - text: 'Concepts', - items: [ - { text: 'Entities', link: '/concepts/entities' }, - { text: 'Static Components', link: '/concepts/static-components' }, - { text: 'Queries', link: '/concepts/queries' }, - ] - }, - { - text: 'References', - items: [ - { text: 'API Reference', link: '/api' }, - ] - }, - { - text: "FAQ", - items: [ - { text: 'How can I contribute?', link: '/faq/contributing' } - ] - }, - { - text: 'Contributing', - items: [ - { text: 'Contribution Guidelines', link: '/contributing/guidelines'}, - { text: 'Submitting Issues', link: '/contributing/issues'}, - { text: 'Submitting Pull Requests', link: '/contributing/pull-requests'}, - ] - } - ], + sidebar: { + "/api/": [ + { + text: "API reference", + items: [ + { text: "jecs", link: "/api/jecs" }, + { text: "World", link: "/api/world" }, + { text: "Query", link: "/api/query" } + ] + } + ], + "/learn/": [ + { + text: "Introduction", + items: [ + { text: 'Getting Started', link: '/overview/get-started' }, + { text: 'First Jecs Project', link: '/overview/first-jecs-project' } + ] + }, + { + text: 'Concepts', + items: [ + { text: 'Entities', link: '/concepts/entities' }, + { text: 'Static Components', link: '/concepts/static-components' }, + { text: 'Queries', link: '/concepts/queries' }, + ] + }, + { + text: "FAQ", + items: [ + { text: 'How can I contribute?', link: '/faq/contributing' } + ] + }, - socialLinks: [ - { icon: 'github', link: 'https://github.com/vuejs/vitepress' } - ] - } + ], + "/contributing/": [ + { + text: 'Contributing', + items: [ + { text: 'Contribution Guidelines', link: '/contributing/guidelines' }, + { text: 'Submitting Issues', link: '/contributing/issues' }, + { text: 'Submitting Pull Requests', link: '/contributing/pull-requests' }, + ] + } + ] + }, + + socialLinks: [ + { icon: 'github', link: 'https://github.com/vuejs/vitepress' } + ] + } }) diff --git a/docs/concepts/queries.md b/docs/concepts/queries.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/concepts/queries.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/concepts/static-components.md b/docs/concepts/static-components.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/concepts/static-components.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/faq/contributing.md b/docs/faq/contributing.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/faq/contributing.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file diff --git a/docs/concepts/entities.md b/docs/learn/concepts/entities.md similarity index 50% rename from docs/concepts/entities.md rename to docs/learn/concepts/entities.md index d3f5a12..8b13789 100644 --- a/docs/concepts/entities.md +++ b/docs/learn/concepts/entities.md @@ -1 +1 @@ - + diff --git a/docs/learn/concepts/queries.md b/docs/learn/concepts/queries.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/concepts/queries.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/concepts/static-components.md b/docs/learn/concepts/static-components.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/concepts/static-components.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/faq/contributing.md b/docs/learn/faq/contributing.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/faq/contributing.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/learn/overview/first-jecs-project.md b/docs/learn/overview/first-jecs-project.md new file mode 100644 index 0000000..1346d9f --- /dev/null +++ b/docs/learn/overview/first-jecs-project.md @@ -0,0 +1,3 @@ +## TODO + +This is a TODO stub. \ No newline at end of file diff --git a/docs/overview/get-started.md b/docs/learn/overview/get-started.md similarity index 95% rename from docs/overview/get-started.md rename to docs/learn/overview/get-started.md index ee09bc0..e7714bb 100644 --- a/docs/overview/get-started.md +++ b/docs/learn/overview/get-started.md @@ -1,130 +1,130 @@ -# Getting Started - -## Installation - -### Installing Standalone - -Navigate to the [releases page](https://github.com/Ukendio/jecs/releases) and download `jecs.rbxm` from the assets. - -![jecs.rbxm](rbxm.png) - -### Using Wally - -Add the following to your wally configuration: - -::: code-group - -```toml [wally.toml] -jecs = "ukendio/jecs@0.2.3" -``` - -::: - -### Using npm (roblox-ts) - -Use one of the following commands on your root project directory: - -::: code-group -```bash [npm] -npm i https://github.com/Ukendio/jecs.git -``` -```bash [yarn] -yarn add https://github.com/Ukendio/jecs.git -``` -```bash [pnpm] -pnpm add https://github.com/Ukendio/jecs.git -``` - -::: - -## Example Usage - -::: code-group - -```luau [Luau] -local world = jecs.World.new() -local pair = jecs.pair -local Wildcard = jecs.Wildcard - -local Name = world:component() - -local function getName(e) - return world:get(e, Name) -end - -local Eats = world:component() - --- Relationship objects -local Apples = world:component() --- components are entities, so you can add components to components -world:set(Apples, Name, "apples") -local Oranges = world:component() -world:set(Oranges, Name, "oranges") - -local bob = world:entity() --- Pairs can be constructed from two entities - -world:set(bob, pair(Eats, Apples), 10) -world:set(bob, pair(Eats, Oranges), 5) -world:set(bob, Name, "bob") - -local alice = world:entity() -world:set(alice, pair(Eats, Apples), 4) -world:set(alice, Name, "alice") - -for id, amount in world:query(pair(Eats, Wildcard)) do - -- get the second target of the pair - local food = world:target(id, Eats) - print(string.format("%s eats %d %s", getName(id), amount, getName(food))) -end - --- Output: --- bob eats 10 apples --- bob eats 5 pears --- alice eats 4 apples -``` - - -```ts [Typescript] -import { Wildcard, pair, World } from "@rbxts/jecs" - - -const world = new World() -const Name = world.component() -function getName(e) { - return world.get(e, Name) -} - -const Eats = world.component() - -// Relationship objects -const Apples = world.component() -// components are entities, so you can add components to components -world.set(Apples, Name, "apples") -const Oranges = world.component() -world.set(Oranges, Name, "oranges") - -const bob = world.entity() -// Pairs can be constructed from two entities - -world.set(bob, pair(Eats, Apples), 10) -world.set(bob, pair(Eats, Oranges), 5) -world.set(bob, Name, "bob") - -const alice = world.entity() -world.set(alice, pair(Eats, Apples), 4) -world.set(alice, Name, "alice") - -for (const [id, amount] of world.query(pair(Eats, Wildcard))) { - // get the second target of the pair - const food = world:target(id, Eats) - print(string.format("%s eats %d %s", getName(id), amount, getName(food))) -} - -// Output: -// bob eats 10 apples -// bob eats 5 pears -// alice eats 4 apples - -``` - +# Getting Started + +## Installation + +### Installing Standalone + +Navigate to the [releases page](https://github.com/Ukendio/jecs/releases) and download `jecs.rbxm` from the assets. + +![jecs.rbxm](rbxm.png) + +### Using Wally + +Add the following to your wally configuration: + +::: code-group + +```toml [wally.toml] +jecs = "ukendio/jecs@0.2.3" +``` + +::: + +### Using npm (roblox-ts) + +Use one of the following commands on your root project directory: + +::: code-group +```bash [npm] +npm i https://github.com/Ukendio/jecs.git +``` +```bash [yarn] +yarn add https://github.com/Ukendio/jecs.git +``` +```bash [pnpm] +pnpm add https://github.com/Ukendio/jecs.git +``` + +::: + +## Example Usage + +::: code-group + +```luau [Luau] +local world = jecs.World.new() +local pair = jecs.pair +local Wildcard = jecs.Wildcard + +local Name = world:component() + +local function getName(e) + return world:get(e, Name) +end + +local Eats = world:component() + +-- Relationship objects +local Apples = world:component() +-- components are entities, so you can add components to components +world:set(Apples, Name, "apples") +local Oranges = world:component() +world:set(Oranges, Name, "oranges") + +local bob = world:entity() +-- Pairs can be constructed from two entities + +world:set(bob, pair(Eats, Apples), 10) +world:set(bob, pair(Eats, Oranges), 5) +world:set(bob, Name, "bob") + +local alice = world:entity() +world:set(alice, pair(Eats, Apples), 4) +world:set(alice, Name, "alice") + +for id, amount in world:query(pair(Eats, Wildcard)) do + -- get the second target of the pair + local food = world:target(id, Eats) + print(string.format("%s eats %d %s", getName(id), amount, getName(food))) +end + +-- Output: +-- bob eats 10 apples +-- bob eats 5 pears +-- alice eats 4 apples +``` + + +```ts [Typescript] +import { Wildcard, pair, World } from "@rbxts/jecs" + + +const world = new World() +const Name = world.component() +function getName(e) { + return world.get(e, Name) +} + +const Eats = world.component() + +// Relationship objects +const Apples = world.component() +// components are entities, so you can add components to components +world.set(Apples, Name, "apples") +const Oranges = world.component() +world.set(Oranges, Name, "oranges") + +const bob = world.entity() +// Pairs can be constructed from two entities + +world.set(bob, pair(Eats, Apples), 10) +world.set(bob, pair(Eats, Oranges), 5) +world.set(bob, Name, "bob") + +const alice = world.entity() +world.set(alice, pair(Eats, Apples), 4) +world.set(alice, Name, "alice") + +for (const [id, amount] of world.query(pair(Eats, Wildcard))) { + // get the second target of the pair + const food = world:target(id, Eats) + print(string.format("%s eats %d %s", getName(id), amount, getName(food))) +} + +// Output: +// bob eats 10 apples +// bob eats 5 pears +// alice eats 4 apples + +``` + diff --git a/docs/overview/rbxm.png b/docs/learn/overview/rbxm.png similarity index 100% rename from docs/overview/rbxm.png rename to docs/learn/overview/rbxm.png diff --git a/docs/public/jecs_logo.svg b/docs/learn/public/jecs_logo.svg similarity index 100% rename from docs/public/jecs_logo.svg rename to docs/learn/public/jecs_logo.svg diff --git a/docs/overview/first-jecs-project.md b/docs/overview/first-jecs-project.md deleted file mode 100644 index 2e03428..0000000 --- a/docs/overview/first-jecs-project.md +++ /dev/null @@ -1,3 +0,0 @@ -## TODO - -This is a TODO stub. \ No newline at end of file