docs: cleanup todo stubs, add code coverage reports, add examples, and pin introduction section (#227)

* Allow pre existing hooks for observer

* Cleanup some todo stubs

* move coverage reports

* use better link for addons

* code coverage page

* make Introduction sidebar visible on all pages and add a few relevant sections

---------

Co-authored-by: Ukendio <ukendio@gmail.com>

docs/.vitepress/config.mts

@@ -15,6 +15,13 @@ export default defineConfig({
 
 		sidebar: {
 			"/api/": [
+				{
+					text: "Introduction",
+					items: [
+						{ text: "Getting Started", link: "/learn/overview/get-started" },
+						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
+					]
+				},
 				{
 					text: "API reference",
 					items: [
@@ -22,7 +29,7 @@ export default defineConfig({
 						{ text: "World", link: "/api/world" },
 						{ text: "Query", link: "/api/query" },
 					],
-				},
+				}
 			],
 			"/learn/": [
 				{
@@ -43,17 +50,35 @@ export default defineConfig({
 					],
 				},
 				{
-					text: "FAQ",
-					items: [{ text: "How can I contribute?", link: "/learn/faq/contributing" }],
+					text: "API Reference",
+					items: [
+						{ text: "jecs", link: "/api/jecs"},
+						{ text: "World", link: "/api/world"},
+						{ text: "Query", link: "/api/query"}
+					]
 				},
+				{
+					text: "Contribute",
+					items: [
+						{ text: "How Can I Contribute?", link: "/contributing/guidelines" }
+					]
+				}
 			],
 			"/contributing/": [
+				{
+					text: "Introduction",
+					items: [
+						{ text: "Getting Started", link: "/learn/overview/get-started" },
+						{ text: "First Jecs Project", link: "/learn/overview/first-jecs-project" },
+					],
+				},
 				{
 					text: "Contributing",
 					items: [
-						{ text: "Contribution Guidelines", link: "/learn/contributing/guidelines" },
-						{ text: "Submitting Issues", link: "/learn/contributing/issues" },
-						{ text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" },
+						{ text: "Contribution Guidelines", link: "/contributing/guidelines" },
+						{ text: "Submitting Issues", link: "/contributing/issues" },
+						{ text: "Submitting Pull Requests", link: "/contributing/pull-requests" },
+						{ text: "Code Coverage", link: "/contributing/coverage" },
 					],
 				},
 			],

docs/contributing/coverage.md

@@ -0,0 +1,17 @@
+# Code Coverage Reports
+
+All of the code coverage reports can be found here:
+
+[Overview](/jecs/coverage/index.html){target="_self"}
+
+[jecs.luau](/jecs/coverage/jecs.luau.html){target="_self"}
+
+[ANSI](/jecs/coverage/ansi.luau.html){target="_self"}
+
+[Entity Visualiser](/jecs/coverage/entity_visualiser.luau.html){target="_self"}
+
+[Lifetime Tracker](/jecs/coverage/lifetime_tracker.luau.html){target="_self"}
+
+[Testkit](/jecs/coverage/testkit.luau.html){target="_self"}
+
+[Tests](/jecs/coverage/tests.luau.html){target="_self"}

docs/contributing/guidelines.md

@@ -1,3 +1,21 @@
-## TODO
+# Contribution Guidelines
 
-This is a TODO stub.
+Whether you found an issue, or want to make a change to jecs, we'd love to hear back from the community on what features you want or bugs you've run into.
+
+There's a few different ways you can go about this.
+
+## Creating an Issue
+
+This is what you should be filing if you have a bug you want to report.
+
+[Click here](https://github.com/Ukendio/jecs/issues/new/choose) to file a bug report. We have a few templates ready for the most common issue types.
+
+Additionally, see the [Submitting Issues](/contributing/issues) page for more information.
+
+## Creating a Pull Request
+
+This is what you should be filing if you have a change you want to merge into the main project.
+
+[Click here](https://github.com/Ukendio/jecs/compare) to select the branch you want to merge from. 
+
+Additionally, see the [Submitting Pull Requests](/contributing/pull-requests) page for more information.

docs/contributing/issues.md

@@ -1,3 +1,25 @@
-## TODO
+# Submitting Issues
+
+When you're submitting an issue, generally they fall into a few categories:
+
+## Bug
+
+We need some information to figure out what's going wrong. At a minimum, you need to tell us:
+
+        (1) What's supposed to happen
+
+        (2) What actually happened
+
+        (3) Steps to reproduce
+
+
+Stack traces and other useful information that you find make a bug report more likely to be fixed.
+
+Consult the template for a bug report if you don't know or have questions about how to format this.
+
+## Documentation
+
+Depending on how you go about it, this can be done as a [Pull Request](/contributing/pull-requests) instead of an issue. Generally, we need to know what was wrong, what you changed, and how it improved the documentation if it isn't obvious.
+
+We just need to know what's wrong. You should fill out a [PR](/contributing/pull-requests) if you know what should be there instead.
 
-This is a TODO stub.

docs/contributing/pull-requests.md

@@ -1,3 +1,77 @@
-## TODO
+# Submitting Pull Requests
 
-This is a TODO stub.
+When submitting a Pull Request, there's a few reasons to do so:
+
+
+## Documentation
+
+If there's something to change with the documentation, you should follow a similar format to this example:
+
+An example of an appropriate typo-fixing PR would be:
+
+>**Brief Description of your Changes**
+>
+>I fixed a couple of typos found in the /contributing/issues.md file.
+>
+>**Impact of your Changes**
+>
+>- Documentation is more clear and readable for the users.
+>
+>**Tests Performed**
+>
+>Ran `vitepress dev docs` and verified it was built successfully.
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+## Change in Behavior
+
+An example of an appropriate PR that adds a new feature would be:
+
+>
+>**Brief Description of your Changes**
+>
+>I added `jecs.best_function`, which gives everyone who uses the module an immediate boost in concurrent player counts. (this is a joke)
+>
+>**Impact of your Changes**
+>
+>- jecs functionality is extended to better fit the needs of the community [explain why].
+>
+>**Tests Performed**
+>
+>Added a few test cases to ensure the function runs as expected [link to changes].
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+## Addons
+
+If you made something you think should be included into the [addons page](/learn/concepts/addons), let us know!
+
+We have tons of examples of libraries and other tools which can be used in conjunction with jecs on this page.
+
+One example of a PR that would be accepted is:
+
+>**Brief Description of your Changes**
+>
+>I added [jecs observers](/learn/concepts/addons#jecs_observers) to the addons page.
+>
+>**Impact of your Changes**
+>
+>- jecs observers are a different and important way of handling queries which benefit the users of jecs by [explain why your tool benefits users here]
+>
+>- [talk about why you went with this design instead of maybe an alternative]
+>
+>**Tests Performed**
+>
+> I used this tool in conjunction with jecs and ensured it works as expected.
+>
+> [If you wrote unit tests for your tool, mention it here.]
+>
+>**Additional Comments**
+>
+>[At Discretion]
+
+Keep in mind the list on the addons page is *not* exhaustive. If you came up with a tool that doesn't fit into any of the categories listed, we still want to hear from you!

docs/learn/concepts/addons.md

@@ -1,6 +1,6 @@
 # Addons
 
-A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](https://github.com/Ukendio/jecs)!
+A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](/contributing/pull-requests#addons)!
 
 # Development tools