Merge branch 'master' of github.com:spacebarchat/docs

spacebarchat · Nov 20, 2023 · 34561e6 · 34561e6
2 parents 6bf5646 + 5813672
commit 34561e6
Show file tree

Hide file tree

Showing 27 changed files with 325 additions and 214 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -1,5 +1,6 @@
 name: Build to GitHub Pages
 on:
+    workflow_dispatch:
     push:
         branches:
             - master
@@ -12,7 +13,8 @@ jobs:
             - uses: actions/setup-python@v2
               with:
                   python-version: 3.x
-            - run: python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index mkdocs-macros-plugin
+            - run: curl https://raw.githubusercontent.com/spacebarchat/spacebarchat/master/CODE_OF_CONDUCT.md -o docs/contributing/conduct.md
+            - run: python3 -m pip install -r requirements.txt
             - run: mkdocs build
             - run: echo docs.spacebar.chat >> site/CNAME
             - name: Deploy 🚀

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
 # Spacebar Docs
 
-[![Build to GitHub Pages](https://github.com/spacebarchat/docs/actions/workflows/build.yml/badge.svg)](https://github.com/spacebarchat/docs/actions/workflows/build.yml) [![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
+[![Build to GitHub Pages](https://github.com/spacebarchat/docs/actions/workflows/build.yml/badge.svg)](https://github.com/spacebarchat/docs/actions/workflows/build.yml)
+[![Netlify Status](https://api.netlify.com/api/v1/badges/86622c9d-4952-4da5-9825-cc016e4a5e5f/deploy-status)](https://app.netlify.com/sites/spacebar-chat/deploys)
+[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
 
 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/spacebarchat/docs)
 
@@ -16,7 +18,7 @@
 3. Install dependencies.
 
     ```bash
-    python3 -m pip install mkdocs-material mkdocs-swagger-ui-tag mkdocs-section-index mkdocs-macros-plugin
+    python3 -m pip install -r requirements.txt
     ```
 
 4. Edit documents(s).

diff --git a/docs/assets/js/missingroutes.js b/docs/assets/js/missingroutes.js
@@ -16,7 +16,16 @@ document
 
 (async () => {
 	const res = await fetch(MISSING_ROUTES_LIST);
-	const missingRoutes = await res.json();
+	const json = await res.json();
+	const missingRoutes = json.routes;
+
+	document.getElementById("counter").innerHTML =
+		`We implement ${json.discord - json.missing}/${
+			json.discord
+		} endpoints from Discord.com ` +
+		`as well as ${
+			json.spacebar + json.missing - json.discord
+		} additional endpoints.`;
 
 	for (let route of missingRoutes) {
 		const elem = document.createElement("li");

diff --git a/docs/assets/overrides/routes.html b/docs/assets/overrides/routes.html
@@ -0,0 +1,31 @@
+<!doctype html>
+<html>
+
+<head>
+	<meta charset="utf-8">
+	<script type="module" src="https://unpkg.com/rapidoc/dist/rapidoc-min.js"></script>
+</head>
+
+<body>
+	<rapi-doc
+		spec-url = "https://raw.githubusercontent.com/spacebarchat/server/master/assets/openapi.json"
+		theme="dark"
+		sort-endpoints-by="none"
+		header-color="#4051b5"
+		primary-color="#4051b5"
+		render-style="focused"
+		schema-expand-level=1
+		schema-style="table"
+		default-schema-tab="schema"
+		show-components="true"
+		heading-text="Spacebar HTTP API Documentation"
+		show-curl-before-try="true"
+		allow-spec-url-load="false"
+		allow-spec-file-load="false"
+	>
+		<a slot="logo" href="https://docs.spacebar.chat" style="margin-left: 20px; width: 30px; height: 30px;">
+			<img style="width: 30px; height: 30px;" src="https://docs.spacebar.chat/assets/logo.svg" />
+		</a>
+</body>
+
+</html>
diff --git a/docs/assets/swagger.css b/docs/assets/swagger.css
diff --git a/docs/contributing/conduct.md b/docs/contributing/conduct.md
diff --git a/docs/contributing/instances.md b/docs/contributing/instances.md
@@ -1,6 +1,6 @@
 # For Instance Owners
 
-The below are the rules for instance owners who look to be featured in our [community instances](https://github.com/spacebarchat/community-instances) list.
+The below are the rules for instance owners who look to be featured in our [community instances](https://github.com/spacebarchat/spacebarchat/tree/master/instances) list.
 If you do not meet these criteria, your instance will simply not be featured on our website.
 
 Your instance:
@@ -13,6 +13,7 @@ Your instance:
 6. Must have a valid and monitored [`general_correspondenceEmail` config](/setup/server/configuration) set.
 7. Must not have default [rights](/setup/server/security/rights) that include operator or other administrative rights.
 8. Enable [Imagor](/setup/server/configuration/imagor), as no image proxy allows attackers to learn user IP addresses.
+9. Have a valid SSL/TLS certificate for all endpoints.
 
 We recommend (not required) that you:
 
@@ -21,3 +22,5 @@ We recommend (not required) that you:
 -   Run your instance under [SystemD](/setup/server/systemd) or a similar system in your distro, for automatic restarting
 -   Provide some mechanism for users to report content. This may be as simple as more openly advertising your correspondence email (i.e. outside `GET /api/policies/instance` or `/api/ping`)
 -   Provide some mechanism for instance status, such as [Grafana](https://grafana.com/).
+-   Host a [`/.well-known/spacebar`](/setup/server/wellknown) file on the domain you wish users associate with your instance, e.g. `spacebar.chat`.
+    If doing so, use this domain as the `url` field in your community instances PR.
diff --git a/docs/contributing/server/missingroute.md b/docs/contributing/server/missingroute.md
@@ -9,15 +9,16 @@ It is generated daily by [{{ repositories.missing_routes }}]({{ repositories.bas
 by scraping the latest Discord.com client.
 
 <div>
- <div class="fc-search">
-  <input
-   id="missing-routes-search"
-   class="md-input md-input--stretch"
-   placeholder="Search missing routes"
-  />
- </div>
- <ul id="missing-routes-list">
- </ul>
+	<div class="fc-search">
+		<input
+			id="missing-routes-search"
+			class="md-input md-input--stretch"
+			placeholder="Search missing routes"
+		/>
+	</div>
+	<p id="counter"></p>
+	<ul id="missing-routes-list">
+	</ul>
 </div>
 
 <script src="/assets/js/missingroutes.js"></script>
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,5 +1,29 @@
 # Frequently Asked Questions
 
+??? info "Is {{ project.name }} still in development? Production Ready?"
+
+    Yes, {{ project.name }} is still in development. Our unpaid team of volunteers is very small though, and so progress is very dependant on our motivation
+    and outside life.
+
+    The [{{ project.name }} server]({{ repositories.base_url }}/{{ repositories.server }}) program has been in development since at least 28/11/2020,
+	and has most core features implemented. API compatibility is reasonable although not quite perfect and so some third party clients may not function,
+    although the official Discord.com client which we test against functions correctly for the most part.
+
+    The big Discord.com features currently left unimplemented or with partial implementations are:
+
+    * Voice/Video support
+    * Voice activities
+    * OAuth2 scopes and other applications (Bot applications work by are left unscoped)
+    * Message threads
+    * Pomelo (new username system without discriminators)
+    * Auto moderation
+
+    For a more complete overview of what is left unimplemented, please refer to [the missing routes viewer](./contributing/server/missingroute.md)
+
+    The [{{ project.name }} client]({{ repositories.base_url }}/{{ repositories.client }}) however is very premature, starting development around 1/03/2023.
+    It is not ready production use or as your daily driver. It lacks many core features and is not recommended to be used.
+	Please setup a third party client, or help contribute to our codebase! Any and all help is appreciated.
+
 ??? info "How do you use the Client?"
 
     As described in [Clients](/setup/clients), the official client is not ready yet. You are free to use

diff --git a/docs/routes.md b/docs/routes.md
@@ -1,10 +1,4 @@
-# API Routes
-
-<style>
- #api-routes, .md-sidebar--secondary {
-  display: none !important;
- }
-</style>
-
-<swagger-ui src="https://raw.githubusercontent.com/{{ repositories.server }}/master/assets/openapi.json"/>
-<!-- <swagger-ui src="/assets/openapi.json"/> -->
+---
+title: HTTP API Docs
+template: routes.html
+---
diff --git a/docs/setup/clients/index.md b/docs/setup/clients/index.md
@@ -1,98 +1 @@
-# Clients
-
-!!! note "The {{ project.name }} client is, at the time of writing this (March 17th, 2023), under heavy development and not ready to be used in production just yet."
-
-!!! warning "Windows support is currently broken."
-
-The official {{ project.name }} client is currently being developed at [this repository]({{ repositories.base_url }}/{{ repositories.client }}/tree/dev/bare-rewrite).
-
-## Official host
-
-We currently host the client at [https://app.{{ project.domain }}](https://app.{{ project.domain }}).
-You can use it to connect to our official instance by default,
-or you can use it to connect to your own by editing your local storage to include the `routeSettings` key with the below example content:
-
-```json
-{
-	"api": "https://staging.{{ project.domain }}/api/v9",
-	"cdn": "https://cdn.staging.{{ project.domain }}",
-	"gateway": "wss://gateway.staging.{{ project.domain }}",
-	"invite": "https://staging.{{ project.domain }}/invite",
-	"template": "https://staging.{{ project.domain }}/template",
-	"gift": "https://staging.{{ project.domain }}/gift",
-	"scheduledEvent": "https://staging.{{ project.domain }}/events"
-}
-```
-
-Replace the above endpoints with your own. If your domain name is `https://whatever.notasite`, then you'll most likely want to enter
-`https://whatever.noasite/api/v9` for the API endpoint, etc.
-
-## Setup/Building
-
-### Dependencies
-
--   [Git](https://git-scm.com/)
--   [NodeJS](https://nodejs.org). Version 16+
--   [yarn](https://yarnpkg.com/) (preferred) or npm
-
-In your terminal:
-
-```bash
-# Download {{ project.name }} Client
-git clone {{ repositories.base_url }}/{{ repositories.client }}.git
-
-# Enter the cloned directory, switch branches to the one, which is actually being developed
-cd {{ project.name.lower() }}-client; git switch dev/bare-rewrite
-
-# Install dependencies
-yarn install
-```
-
-To start the client with Metro for development, run
-
-```bash
-yarn start
-```
-
-!!! note "Platform-specific development commands:"
-
-    For development for Android, run
-
-    ```bash
-    yarn android
-    ```
-
-    For development for iOS, run
-
-    ```bash
-    yarn ios
-    ```
-
-    For development for Windows, run
-
-    ```bash
-    yarn windows
-    ```
-
-To build static files for the web (i.e. when hosting it yourself), run
-
-```bash
-yarn build:web
-```
-
-Files will be built to `web-build`
-
-## Contributing
-
-To contribute:
-
--   [Fork the repository]({{ repositories.base_url }}/{{ repositories.client }}/fork)
--   Run the building instructions.
--   Commit & Push.
--   Pull Request & Done!
-
-### What can I contribute?
-
--   "Core" features like settings, editing messages, dms, markdown rendering, etc. What do you think are basic features that you would want? Some of the GitHub Issues apply to this.
--   Implementing other things like voice/video is fine too, though
--   [This]({{ repositories.base_url }}/{{ repositories.client }}/issues/21) is a good starting point and lists the core features that are still missing from the client.
+## [Official Client](official)
diff --git a/docs/setup/clients/official/index.md b/docs/setup/clients/official/index.md
@@ -0,0 +1,6 @@
+# {{ project.name }} Client
+
+The {{ project.name }} client has 2 versions:
+
+-   The new, React version which is currently under active development. Docs: [React Client](react.md)
+-   The old, legacy React Native version which is no longer under active development. Docs: [Legacy Client](legacy.md)