From e8dde0396f76941b451a7082b3c4eefa4d376694 Mon Sep 17 00:00:00 2001 From: Dessalines Date: Sun, 13 Sep 2020 12:54:18 -0500 Subject: [PATCH] Fixing up docs. --- README.md | 2 +- docker/federation/run-tests.sh | 2 +- docs/src/about_features.md | 1 + docs/src/contributing.md | 7 +- docs/src/contributing_docker_development.md | 4 +- docs/src/contributing_local_development.md | 33 ++-- docs/src/contributing_tests.md | 2 +- docs/src/contributing_theming.md | 5 +- docs/src/contributing_websocket_http_api.md | 178 +++++++++++++++----- 9 files changed, 166 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 57b3d63e5..0d4a73f9a 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@

- +

Lemmy

diff --git a/docker/federation/run-tests.sh b/docker/federation/run-tests.sh index bb4a29d68..705ba161d 100755 --- a/docker/federation/run-tests.sh +++ b/docker/federation/run-tests.sh @@ -15,7 +15,7 @@ sudo chown -R 991:991 volumes/pictrs_alpha sudo docker-compose up -d -pushd ../../ui +pushd ../../api_tests echo "Waiting for Lemmy to start..." while [[ "$(curl -s -o /dev/null -w '%{http_code}' 'localhost:8540/api/v1/site')" != "200" ]]; do sleep 1; done while [[ "$(curl -s -o /dev/null -w '%{http_code}' 'localhost:8550/api/v1/site')" != "200" ]]; do sleep 1; done diff --git a/docs/src/about_features.md b/docs/src/about_features.md index a8371fc4d..7c8d95a96 100644 --- a/docs/src/about_features.md +++ b/docs/src/about_features.md @@ -31,4 +31,5 @@ - High performance. - Server is written in rust. - Front end is `~80kB` gzipped. + - Front end works without javascript (read-only). - Supports arm64 / Raspberry Pi. diff --git a/docs/src/contributing.md b/docs/src/contributing.md index fdfaa2b84..b28255896 100644 --- a/docs/src/contributing.md +++ b/docs/src/contributing.md @@ -18,13 +18,14 @@ Check out [Lemmy's Weblate](https://weblate.yerbamate.dev/projects/lemmy/) for t ### Front end - The front end is written in `typescript`, using a react-like framework called [inferno](https://infernojs.org/). All UI elements are reusable `.tsx` components. -- The main page and routing are in `ui/src/index.tsx`. -- The components are located in `ui/src/components`. +- The front end repository is [lemmy-isomorphic-ui](https://github.com/LemmyNet/lemmy-isomorphic-ui). +- The routes are at `src/shared/routes.ts`. +- The components are located in `src/shared/components`. ### Back end - The back end is written in `rust`, using `diesel`, and `actix`. -- The server source code is split into main sections in `server/src`. These include: +- The server source code is split into main sections in `src`. These include: - `db` - The low level database actions. - Database additions are done using diesel migrations. Run `diesel migration generate xxxxx` to add new things. - `api` - The high level user interactions (things like `CreateComment`) diff --git a/docs/src/contributing_docker_development.md b/docs/src/contributing_docker_development.md index afa051072..23b9fa005 100644 --- a/docs/src/contributing_docker_development.md +++ b/docs/src/contributing_docker_development.md @@ -9,7 +9,9 @@ cd lemmy/docker/dev sudo docker-compose up --no-deps --build ``` -and go to http://localhost:8536. +and go to http://localhost:1235. + +*Note: many features (like docs and pictures) will not work without using an nginx profile like that in `ansible/templates/nginx.conf`. To speed up the Docker compile, add the following to `/etc/docker/daemon.json` and restart Docker. ``` diff --git a/docs/src/contributing_local_development.md b/docs/src/contributing_local_development.md index 5bfbfdd10..1be5ee881 100644 --- a/docs/src/contributing_local_development.md +++ b/docs/src/contributing_local_development.md @@ -20,29 +20,31 @@ Finally, install Node and Yarn. brew install node yarn ``` -### Get the source code +### Get the back end source code ``` git clone https://github.com/LemmyNet/lemmy.git # or alternatively from gitea # git clone https://yerbamate.dev/LemmyNet/lemmy.git ``` -All the following commands need to be run either in `lemmy/server` or `lemmy/ui`, as indicated -by the `cd` command. - ### Build the backend (Rust) ``` cargo build # for development, use `cargo check` instead) ``` +### Get the front end source code +``` +git clone https://github.com/LemmyNet/lemmy-isomorphic-ui.git +``` + ### Setup postgresql #### Ubuntu ``` sudo apt install postgresql sudo systemctl start postgresql -# Either execute server/db-init.sh, or manually initialize the postgres database: +# Either execute db-init.sh, or manually initialize the postgres database: sudo -u postgres psql -c "create user lemmy with password 'password' superuser;" -U postgres sudo -u postgres psql -c 'create database lemmy with owner lemmy;' -U postgres export LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy @@ -54,7 +56,7 @@ brew install postgresql brew services start postgresql /usr/local/opt/postgres/bin/createuser -s postgres -# Either execute server/db-init.sh, or manually initialize the postgres database: +# Either execute db-init.sh, or manually initialize the postgres database: psql -c "create user lemmy with password 'password' superuser;" -U postgres psql -c 'create database lemmy with owner lemmy;' -U postgres export LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy @@ -62,21 +64,22 @@ export LEMMY_DATABASE_URL=postgres://lemmy:password@localhost:5432/lemmy ### Run a local development instance ``` -# run each of these in a seperate terminal -cd server && cargo run -cd ui && yarn start +cd lemmy +cargo run ``` -Then open [localhost:4444](http://localhost:4444) in your browser. It will auto-refresh if you edit -any frontend files. For backend coding, you will have to rerun `cargo run`. You can use -`cargo check` as a faster way to find compilation errors. +Then open [localhost:1235](http://localhost:1235) in your browser. To reload back-end changes, you will have to rerun `cargo run`. You can use `cargo check` as a faster way to find compilation errors. + +To do front end development: -To speed up incremental builds, you can add the following to `~/.cargo/config`: ``` -[target.x86_64-unknown-linux-gnu] -rustflags = ["-Clink-arg=-fuse-ld=lld"] +cd lemmy-isomorphic-ui +yarn +yarn dev ``` +and goto [localhost:1234](http://localhost:1234). Front end saves should rebuild the project. + Note that this setup doesn't include image uploads or link previews (provided by pict-rs and iframely respectively). If you want to test those, you should use the [Docker development](contributing_docker_development.md). diff --git a/docs/src/contributing_tests.md b/docs/src/contributing_tests.md index d4168e190..e40836c30 100644 --- a/docs/src/contributing_tests.md +++ b/docs/src/contributing_tests.md @@ -3,7 +3,7 @@ #### Rust After installing [local development dependencies](contributing_local_development.md), run the -following commands in the `server` subfolder: +following commands: ```bash psql -U lemmy -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;" diff --git a/docs/src/contributing_theming.md b/docs/src/contributing_theming.md index 25c8ca6d1..d5ca29a0e 100644 --- a/docs/src/contributing_theming.md +++ b/docs/src/contributing_theming.md @@ -12,7 +12,8 @@ Lemmy uses [Bootstrap v4](https://getbootstrap.com/), and very few custom css cl ## Adding -1. Copy `{my-theme-name}.min.css` to `ui/assets/css/themes`. (You can also copy the `_variables.scss` here if you want). -1. Go to `ui/src/utils.ts` and add `{my-theme-name}` to the themes list. +1. Fork the [lemmy-isomorphic-ui](https://github.com/LemmyNet/lemmy-isomorphic-ui). +1. Copy `{my-theme-name}.min.css` to `src/assets/css/themes`. (You can also copy the `_variables.scss` here if you want). +1. Go to `src/shared/utils.ts` and add `{my-theme-name}` to the themes list. 1. Test locally 1. Do a pull request with those changes. diff --git a/docs/src/contributing_websocket_http_api.md b/docs/src/contributing_websocket_http_api.md index a167016a2..060207ac9 100644 --- a/docs/src/contributing_websocket_http_api.md +++ b/docs/src/contributing_websocket_http_api.md @@ -1,6 +1,6 @@ # Lemmy API -*Note: this may lag behind the actual API endpoints [here](../server/src/api). The API should be considered unstable and may change any time.* +*Note: this may lag behind the actual API endpoints [here](../src/api). The API should be considered unstable and may change any time.* @@ -88,162 +88,174 @@ - [Request](#request-16) - [Response](#response-16) - [HTTP](#http-17) - * [Site](#site) - + [List Categories](#list-categories) + + [User Join](#user-join) - [Request](#request-17) - [Response](#response-17) - [HTTP](#http-18) - + [Search](#search) + * [Site](#site) + + [List Categories](#list-categories) - [Request](#request-18) - [Response](#response-18) - [HTTP](#http-19) - + [Get Modlog](#get-modlog) + + [Search](#search) - [Request](#request-19) - [Response](#response-19) - [HTTP](#http-20) - + [Create Site](#create-site) + + [Get Modlog](#get-modlog) - [Request](#request-20) - [Response](#response-20) - [HTTP](#http-21) - + [Edit Site](#edit-site) + + [Create Site](#create-site) - [Request](#request-21) - [Response](#response-21) - [HTTP](#http-22) - + [Get Site](#get-site) + + [Edit Site](#edit-site) - [Request](#request-22) - [Response](#response-22) - [HTTP](#http-23) - + [Transfer Site](#transfer-site) + + [Get Site](#get-site) - [Request](#request-23) - [Response](#response-23) - [HTTP](#http-24) - + [Get Site Config](#get-site-config) + + [Transfer Site](#transfer-site) - [Request](#request-24) - [Response](#response-24) - [HTTP](#http-25) - + [Save Site Config](#save-site-config) + + [Get Site Config](#get-site-config) - [Request](#request-25) - [Response](#response-25) - [HTTP](#http-26) - * [Community](#community) - + [Get Community](#get-community) + + [Save Site Config](#save-site-config) - [Request](#request-26) - [Response](#response-26) - [HTTP](#http-27) - + [Create Community](#create-community) + * [Community](#community) + + [Get Community](#get-community) - [Request](#request-27) - [Response](#response-27) - [HTTP](#http-28) - + [List Communities](#list-communities) + + [Create Community](#create-community) - [Request](#request-28) - [Response](#response-28) - [HTTP](#http-29) - + [Ban from Community](#ban-from-community) + + [List Communities](#list-communities) - [Request](#request-29) - [Response](#response-29) - [HTTP](#http-30) - + [Add Mod to Community](#add-mod-to-community) + + [Ban from Community](#ban-from-community) - [Request](#request-30) - [Response](#response-30) - [HTTP](#http-31) - + [Edit Community](#edit-community) + + [Add Mod to Community](#add-mod-to-community) - [Request](#request-31) - [Response](#response-31) - [HTTP](#http-32) - + [Delete Community](#delete-community) + + [Edit Community](#edit-community) - [Request](#request-32) - [Response](#response-32) - [HTTP](#http-33) - + [Remove Community](#remove-community) + + [Delete Community](#delete-community) - [Request](#request-33) - [Response](#response-33) - [HTTP](#http-34) - + [Follow Community](#follow-community) + + [Remove Community](#remove-community) - [Request](#request-34) - [Response](#response-34) - [HTTP](#http-35) - + [Get Followed Communities](#get-followed-communities) + + [Follow Community](#follow-community) - [Request](#request-35) - [Response](#response-35) - [HTTP](#http-36) - + [Transfer Community](#transfer-community) + + [Get Followed Communities](#get-followed-communities) - [Request](#request-36) - [Response](#response-36) - [HTTP](#http-37) - * [Post](#post) - + [Create Post](#create-post) + + [Transfer Community](#transfer-community) - [Request](#request-37) - [Response](#response-37) - [HTTP](#http-38) - + [Get Post](#get-post) + + [Community Join](#community-join) - [Request](#request-38) - [Response](#response-38) - [HTTP](#http-39) - + [Get Posts](#get-posts) + * [Post](#post) + + [Create Post](#create-post) - [Request](#request-39) - [Response](#response-39) - [HTTP](#http-40) - + [Create Post Like](#create-post-like) + + [Get Post](#get-post) - [Request](#request-40) - [Response](#response-40) - [HTTP](#http-41) - + [Edit Post](#edit-post) + + [Get Posts](#get-posts) - [Request](#request-41) - [Response](#response-41) - [HTTP](#http-42) - + [Delete Post](#delete-post) + + [Create Post Like](#create-post-like) - [Request](#request-42) - [Response](#response-42) - [HTTP](#http-43) - + [Remove Post](#remove-post) + + [Edit Post](#edit-post) - [Request](#request-43) - [Response](#response-43) - [HTTP](#http-44) - + [Lock Post](#lock-post) + + [Delete Post](#delete-post) - [Request](#request-44) - [Response](#response-44) - [HTTP](#http-45) - + [Sticky Post](#sticky-post) + + [Remove Post](#remove-post) - [Request](#request-45) - [Response](#response-45) - [HTTP](#http-46) - + [Save Post](#save-post) + + [Lock Post](#lock-post) - [Request](#request-46) - [Response](#response-46) - [HTTP](#http-47) - * [Comment](#comment) - + [Create Comment](#create-comment) + + [Sticky Post](#sticky-post) - [Request](#request-47) - [Response](#response-47) - [HTTP](#http-48) - + [Edit Comment](#edit-comment) + + [Save Post](#save-post) - [Request](#request-48) - [Response](#response-48) - [HTTP](#http-49) - + [Delete Comment](#delete-comment) + + [Post Join](#post-join) - [Request](#request-49) - [Response](#response-49) - [HTTP](#http-50) - + [Remove Comment](#remove-comment) + * [Comment](#comment) + + [Create Comment](#create-comment) - [Request](#request-50) - [Response](#response-50) - [HTTP](#http-51) - + [Get Comments](#get-comments) + + [Edit Comment](#edit-comment) - [Request](#request-51) - [Response](#response-51) - [HTTP](#http-52) - + [Mark Comment as Read](#mark-comment-as-read) + + [Delete Comment](#delete-comment) - [Request](#request-52) - [Response](#response-52) - [HTTP](#http-53) - + [Save Comment](#save-comment) + + [Remove Comment](#remove-comment) - [Request](#request-53) - [Response](#response-53) - [HTTP](#http-54) - + [Create Comment Like](#create-comment-like) + + [Get Comments](#get-comments) - [Request](#request-54) - [Response](#response-54) - [HTTP](#http-55) + + [Mark Comment as Read](#mark-comment-as-read) + - [Request](#request-55) + - [Response](#response-55) + - [HTTP](#http-56) + + [Save Comment](#save-comment) + - [Request](#request-56) + - [Response](#response-56) + - [HTTP](#http-57) + + [Create Comment Like](#create-comment-like) + - [Request](#request-57) + - [Response](#response-57) + - [HTTP](#http-58) * [RSS / Atom feeds](#rss--atom-feeds) + [All](#all) + [Community](#community-1) @@ -257,7 +269,7 @@ - Option<***SomeType***> designates an option which may be omitted in requests and not be present in responses. It will be of type ***SomeType***. - Vec<***SomeType***> is a list which contains objects of type ***SomeType***. - `chrono::NaiveDateTime` is a timestamp string in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format. Timestamps will be UTC. -- Other data types are listed [here](../server/src/db). +- Other data types are listed [here](../src/db). ## Basic usage @@ -269,6 +281,12 @@ Connect to ws://***host***/api/v1/ws to get started. If the ***`host`*** supports secure connections, you can use wss://***host***/api/v1/ws. +To receive websocket messages, you must join a room / context. The three available are: + +- [UserJoin](#user-join). Receives replies, private messages, etc. +- [PostJoin](#post-join). Receives new comments on a post. +- [CommunityJoin](#community-join). Receives front page / community posts. + #### Testing with Websocat [Websocat link](https://github.com/vi/websocat) @@ -847,6 +865,29 @@ Marks all user replies and mentions as read. `POST /user/ban` +#### User Join +##### Request +```rust +{ + op: "UserJoin", + data: { + auth: String + } +} +``` +##### Response +```rust +{ + op: "UserJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /user/join` + ### Site #### List Categories ##### Request @@ -1395,6 +1436,32 @@ Only admins can remove a community. `POST /community/transfer` +#### Community Join + +The main / frontpage community is `community_id: 0`. + +##### Request +```rust +{ + op: "CommunityJoin", + data: { + community_id: i32 + } +} +``` +##### Response +```rust +{ + op: "CommunityJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /community/join` + ### Post #### Create Post ##### Request @@ -1679,6 +1746,29 @@ Only admins and mods can sticky a post. `POST /post/save` +#### Post Join +##### Request +```rust +{ + op: "PostJoin", + data: { + post_id: i32 + } +} +``` +##### Response +```rust +{ + op: "PostJoin", + data: { + joined: bool, + } +} +``` +##### HTTP + +`POST /post/join` + ### Comment #### Create Comment ##### Request