From: Felix Ableitner <me@nutomic.com>
Date: Sun, 29 Nov 2020 12:09:14 +0000 (+0100)
Subject: Rewrite federation docs
X-Git-Url: http://these/git/%7B%60%24%7BwebArchiveUrl%7D/%22%7B%7D/%22https:/nerdica.net/%7Biframely.url%7D?a=commitdiff_plain;h=55e03c4eb4dfeb79c5603289e541279fd39036b0;p=lemmy.git

Rewrite federation docs
---

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index e00f5ced..93f6c42d 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -1,23 +1,25 @@
 # Summary
 
-- [About](about.md)
-  - [Features](about_features.md)
-  - [Goals](about_goals.md)
-  - [Post and Comment Ranking](about_ranking.md)
-  - [Guide](about_guide.md)
-- [Administration](administration.md)
-  - [Install with Docker](administration_install_docker.md)
-  - [Install with Ansible](administration_install_ansible.md)
-  - [Configuration](administration_configuration.md)
-  - [Backup and Restore](administration_backup_and_restore.md)
-  - [Federation](administration_federation.md)
-- [Contributing](contributing.md)
-  - [Docker Development](contributing_docker_development.md)
-  - [Local Development](contributing_local_development.md)
-  - [Tests](contributing_tests.md)
-  - [Federation Development](contributing_federation_development.md)
-  - [Websocket/HTTP API](contributing_websocket_http_api.md)
-  - [Federation Overview](contributing_federation_overview.md)
-  - [ActivityPub API Outline](contributing_apub_api_outline.md)
-  - [Theming Guide](contributing_theming.md)
+- [About](about/about.md)
+  - [Features](about/features.md)
+  - [Goals](about/goals.md)
+  - [Post and Comment Ranking](about/ranking.md)
+  - [Guide](about/guide.md)
+- [Administration](administration/administration.md)
+  - [Install with Docker](administration/install_docker.md)
+  - [Install with Ansible](administration/install_ansible.md)
+  - [Configuration](administration/configuration.md)
+  - [Backup and Restore](administration/backup_and_restore.md)
+- [Federation](federation/federation.md)
+  - [Federation Overview](federation/overview.md)
+  - [Administration](federation/administration.md)
+  - [Resources](federation/resources.md)
+  - [Lemmy Protocol](federation/lemmy_protocol.md)
+- [Contributing](contributing/contributing.md)
+  - [Docker Development](contributing/docker_development.md)
+  - [Local Development](contributing/local_development.md)
+  - [Theming Guide](contributing/theming.md)
+  - [Tests](contributing/tests.md)
+  - [Websocket/HTTP API](contributing/websocket_http_api.md)
+  - [Federation Development](contributing/federation_development.md)
 - [Lemmy Council](lemmy_council.md)
diff --git a/docs/src/about.md b/docs/src/about/about.md
similarity index 100%
rename from docs/src/about.md
rename to docs/src/about/about.md
diff --git a/docs/src/about_features.md b/docs/src/about/features.md
similarity index 100%
rename from docs/src/about_features.md
rename to docs/src/about/features.md
diff --git a/docs/src/about_goals.md b/docs/src/about/goals.md
similarity index 69%
rename from docs/src/about_goals.md
rename to docs/src/about/goals.md
index e0427481..e7d8e8dc 100644
--- a/docs/src/about_goals.md
+++ b/docs/src/about/goals.md
@@ -36,19 +36,3 @@
 - [Rust docker build](https://shaneutt.com/blog/rust-fast-small-docker-image-builds/)
 - [Zurb mentions](https://github.com/zurb/tribute)
 - [TippyJS](https://github.com/atomiks/tippyjs)
-
-## Activitypub guides
-
-- https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/
-- https://raw.githubusercontent.com/w3c/activitypub/gh-pages/activitypub-tutorial.txt
-- https://github.com/tOkeshu/activitypub-example
-- https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/
-- Use the [activitypub crate.](https://docs.rs/activitypub/0.1.4/activitypub/)
-- https://docs.rs/activitypub/0.1.4/activitypub/
-- [Activitypub vocab.](https://www.w3.org/TR/activitystreams-vocabulary/)
-- [Activitypub main](https://www.w3.org/TR/activitypub/)
-- [Federation.md](https://github.com/dariusk/gathio/blob/7fc93dbe9d4d99457a0e85c6c532112f415b7af2/FEDERATION.md)
-- [Activitypub implementers guide](https://socialhub.activitypub.rocks/t/draft-guide-for-new-activitypub-implementers/479)
-- [Data storage questions](https://socialhub.activitypub.rocks/t/data-storage-questions/579/3)
-- [Activitypub as it has been understood](https://flak.tedunangst.com/post/ActivityPub-as-it-has-been-understood)
-- [Asonix http signatures in rust](https://git.asonix.dog/Aardwolf/http-signature-normalization)
diff --git a/docs/src/about_guide.md b/docs/src/about/guide.md
similarity index 96%
rename from docs/src/about_guide.md
rename to docs/src/about/guide.md
index d9f8adb0..59244b1e 100644
--- a/docs/src/about_guide.md
+++ b/docs/src/about/guide.md
@@ -17,7 +17,7 @@ Hot | Trending sort based on the score, and the post creation time.
 New | Newest items.
 Top | The highest scoring items in the given time frame.
 
-For more detail, check the [Post and Comment Ranking details](about_ranking.md).
+For more detail, check the [Post and Comment Ranking details](ranking.md).
 
 ## Markdown Guide
 
diff --git a/docs/src/about_ranking.md b/docs/src/about/ranking.md
similarity index 100%
rename from docs/src/about_ranking.md
rename to docs/src/about/ranking.md
diff --git a/docs/src/administration.md b/docs/src/administration/administration.md
similarity index 73%
rename from docs/src/administration.md
rename to docs/src/administration/administration.md
index 690b7159..3211859b 100644
--- a/docs/src/administration.md
+++ b/docs/src/administration/administration.md
@@ -4,7 +4,7 @@ Information for Lemmy instance admins, and those who want to run a server.
 
 ## Install
 
-Lemmy has two primary install methods, [docker](administration_install_docker.md), and [ansible](administration_install_ansible.md). Ansible simplifies deploying to a remote server, while docker is best for local testing.
+Lemmy has two primary install methods, [docker](install_docker.md), and [ansible](install_ansible.md). Ansible simplifies deploying to a remote server, while docker is best for local testing.
 
 ### Manual install
 
diff --git a/docs/src/administration_backup_and_restore.md b/docs/src/administration/backup_and_restore.md
similarity index 100%
rename from docs/src/administration_backup_and_restore.md
rename to docs/src/administration/backup_and_restore.md
diff --git a/docs/src/administration_configuration.md b/docs/src/administration/configuration.md
similarity index 100%
rename from docs/src/administration_configuration.md
rename to docs/src/administration/configuration.md
diff --git a/docs/src/administration_install_ansible.md b/docs/src/administration/install_ansible.md
similarity index 78%
rename from docs/src/administration_install_ansible.md
rename to docs/src/administration/install_ansible.md
index 849957ad..ea04f53d 100644
--- a/docs/src/administration_install_ansible.md
+++ b/docs/src/administration/install_ansible.md
@@ -1,6 +1,6 @@
 # Ansible Installation
 
-This is the same as the [Docker installation](administration_install_docker.md), except that Ansible handles all of it automatically. It also does some extra things like setting up TLS and email for your Lemmy instance.
+This is the same as the [Docker installation](install_docker.md), except that Ansible handles all of it automatically. It also does some extra things like setting up TLS and email for your Lemmy instance.
 
 First, you need to [install Ansible on your local computer](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) (e.g. using `sudo apt install ansible`) or the equivalent for you platform.
 
diff --git a/docs/src/administration_install_docker.md b/docs/src/administration/install_docker.md
similarity index 91%
rename from docs/src/administration_install_docker.md
rename to docs/src/administration/install_docker.md
index 490fe1c0..4796fe52 100644
--- a/docs/src/administration_install_docker.md
+++ b/docs/src/administration/install_docker.md
@@ -27,7 +27,7 @@ Open up your `docker-compose.yml`, and make sure `LEMMY_EXTERNAL_HOST` for `lemm
 
 If you'd like a different database password, you should also change it in the `docker-compose.yml` **before** your first run.
 
-After this, have a look at the [config file](administration_configuration.md) named `lemmy.hjson`, and adjust it, in particular the hostname, and possibly the db password. Then run:
+After this, have a look at the [config file](configuration.md) named `lemmy.hjson`, and adjust it, in particular the hostname, and possibly the db password. Then run:
 
 `docker-compose up -d`
 
diff --git a/docs/src/contributing.md b/docs/src/contributing/contributing.md
similarity index 100%
rename from docs/src/contributing.md
rename to docs/src/contributing/contributing.md
diff --git a/docs/src/contributing_docker_development.md b/docs/src/contributing/docker_development.md
similarity index 91%
rename from docs/src/contributing_docker_development.md
rename to docs/src/contributing/docker_development.md
index 3272efe2..ee035dd2 100644
--- a/docs/src/contributing_docker_development.md
+++ b/docs/src/contributing/docker_development.md
@@ -29,4 +29,4 @@ To speed up the Docker compile, add the following to `/etc/docker/daemon.json` a
 ```
 
 If the build is still too slow, you will have to use a
-[local build](contributing_local_development.md) instead.
+[local build](local_development.md) instead.
diff --git a/docs/src/contributing_federation_development.md b/docs/src/contributing/federation_development.md
similarity index 91%
rename from docs/src/contributing_federation_development.md
rename to docs/src/contributing/federation_development.md
index 0c6fd9c4..fd625d60 100644
--- a/docs/src/contributing_federation_development.md
+++ b/docs/src/contributing/federation_development.md
@@ -2,7 +2,7 @@
 
 ## Running locally
 
-Install the dependencies as described in [Docker development](contributing_docker_development.md). Then run the following
+Install the dependencies as described in [Docker development](docker_development.md). Then run the following
 
 ```bash
 cd docker/federation
@@ -34,8 +34,8 @@ Firefox containers are a good way to test them interacting.
 
 Note that federation is currently in alpha. **Only use it for testing**, not on any production server, and be aware that turning on federation may break your instance.
 
-Follow the normal installation instructions, either with [Ansible](administration_install_ansible.md) or
-[manually](administration_install_docker.md). Then replace the line `image: dessalines/lemmy:v0.x.x` in 
+Follow the normal installation instructions, either with [Ansible](../administration/install_ansible.md) or
+[manually](../administration/install_docker.md). Then replace the line `image: dessalines/lemmy:v0.x.x` in 
 `/lemmy/docker-compose.yml` with `image: dessalines/lemmy:federation`. Also add the following in
 `/lemmy/lemmy.hjson`:
 
diff --git a/docs/src/contributing_local_development.md b/docs/src/contributing/local_development.md
similarity index 97%
rename from docs/src/contributing_local_development.md
rename to docs/src/contributing/local_development.md
index ccf1f51e..114a5458 100644
--- a/docs/src/contributing_local_development.md
+++ b/docs/src/contributing/local_development.md
@@ -85,4 +85,4 @@ and go to [localhost:1234](http://localhost:1234). Front end saves should rebuil
 
 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).
+[Docker development](docker_development.md).
diff --git a/docs/src/contributing_tests.md b/docs/src/contributing/tests.md
similarity index 51%
rename from docs/src/contributing_tests.md
rename to docs/src/contributing/tests.md
index 494cf5cd..e4cfa65a 100644
--- a/docs/src/contributing_tests.md
+++ b/docs/src/contributing/tests.md
@@ -2,7 +2,7 @@
 
 #### Rust
 
-After installing [local development dependencies](contributing_local_development.md), run the
+After installing [local development dependencies](local_development.md), run the
 following commands:
 
 ```bash
@@ -12,7 +12,7 @@ psql -U lemmy -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
 
 ### Federation
 
-Install the [Docker development dependencies](contributing_docker_development.md), and execute:
+Install the [Docker development dependencies](docker_development.md), and execute:
 
 ```
 cd docker/federation
diff --git a/docs/src/contributing_theming.md b/docs/src/contributing/theming.md
similarity index 100%
rename from docs/src/contributing_theming.md
rename to docs/src/contributing/theming.md
diff --git a/docs/src/contributing_websocket_http_api.md b/docs/src/contributing/websocket_http_api.md
similarity index 100%
rename from docs/src/contributing_websocket_http_api.md
rename to docs/src/contributing/websocket_http_api.md
diff --git a/docs/src/administration_federation.md b/docs/src/federation/administration.md
similarity index 96%
rename from docs/src/administration_federation.md
rename to docs/src/federation/administration.md
index c7044ac2..fc24216c 100644
--- a/docs/src/administration_federation.md
+++ b/docs/src/federation/administration.md
@@ -1,4 +1,4 @@
-# Federation 
+# Federation Administration
 
 Note: ActivityPub federation is still under development. We recommend that you only enable it on test instances for now.
 
@@ -11,6 +11,7 @@ Federation does not start automatically, but needs to be triggered manually thro
 - `https://lemmy.ml/c/programming` (Community)
 - `https://lemmy.ml/u/nutomic` (User)
 - `https://lemmy.ml/post/123` (Post)
+- `https://lemmy.ml/comment/321` (Comment)
 
 For an overview of how federation in Lemmy works on a technical level, check out our [Federation Overview](contributing_federation_overview.md).
 
diff --git a/docs/src/federation/federation.md b/docs/src/federation/federation.md
new file mode 100644
index 00000000..28e304d5
--- /dev/null
+++ b/docs/src/federation/federation.md
@@ -0,0 +1,14 @@
+# Federation
+
+Lemmy uses the ActivityPub protocol (a W3C standard) to enable federation between different servers (often called instances). This is very similar to the way email works. For example, if you use gmail.com, then you can't just send mails to other gmail.com users, but also to yahoo.com, yandex.ru and so on. Email uses the SMTP protocol to achieve this, so you can think of ActivityPub as "SMTP for social media". The amount of different actions possible on social media (post, comment, like, share, etc) means that ActivityPub is much more complicated than SMTP.
+
+As with email, ActivityPub federation happens only between servers. So if you are registered on `enterprise.lemmy.ml`, you only connect to the API of `enterprise.lemmy.ml`, while the server takes care of sending and receiving data from other instances (eg `voyager.lemmy.ml`). The great advantage of this approach is that the average user doesn't have to do anything to use federation. In fact if you are using Lemmy, you are likely already using it. One way to confirm is by going to a community or user profile. If you are on `enterprise.lemmy.ml` and you see a user like `@nutomic@voyager.lemmy.ml`, or a community like `!main@ds9.lemmy.ml`, then those are federated, meaning they use a different instance from yours.
+
+One way you can take advantage of federation is by opening a different instance, like `ds9.lemmy.ml`, and browsing it. If you see an interesting community, post or user that you want to interact with, just copy its URL and paste it into the search of your own instance. Your instance will connect to the other one (assuming the allowlist/blocklist allows it), and directly display the remote content to you, so that you can follow a community or comment on a post. Here are some examples of working searches:
+
+- `!main@lemmy.ml` (Community)
+- `@nutomic@lemmy.ml` (User)
+- `https://lemmy.ml/c/programming` (Community)
+- `https://lemmy.ml/u/nutomic` (User)
+- `https://lemmy.ml/post/123` (Post)
+- `https://lemmy.ml/comment/321` (Comment)
\ No newline at end of file
diff --git a/docs/src/contributing_apub_api_outline.md b/docs/src/federation/lemmy_protocol.md
similarity index 98%
rename from docs/src/contributing_apub_api_outline.md
rename to docs/src/federation/lemmy_protocol.md
index 92cdf9c0..75dfe263 100644
--- a/docs/src/contributing_apub_api_outline.md
+++ b/docs/src/federation/lemmy_protocol.md
@@ -1,4 +1,6 @@
-# Activitypub API outline
+# Lemmy Federation Protocol
+
+The Lemmy Protocol (or Lemmy Federation Protocol) is a strict subset of the [ActivityPub Protocol](https://www.w3.org/TR/activitypub/). Any deviation from the ActivityPub protocol is a bug in Lemmy or in this documentation (or both).
 
 This document is targeted at developers who are familiar with the ActivityPub and ActivityStreams protocols. It gives a detailed outline of the actors, objects and activities used by Lemmy.
 
diff --git a/docs/src/contributing_federation_overview.md b/docs/src/federation/overview.md
similarity index 99%
rename from docs/src/contributing_federation_overview.md
rename to docs/src/federation/overview.md
index abfac455..949984b8 100644
--- a/docs/src/contributing_federation_overview.md
+++ b/docs/src/federation/overview.md
@@ -1,4 +1,4 @@
-# Federation
+# Federation Overview
 
 
 This document is for anyone who wants to know how Lemmy federation works, without being overly technical. It is meant provide a high-level overview of ActivityPub federation in Lemmy. If you are implementing ActivityPub yourself and want to be compatible with Lemmy, read our [ActivityPub API outline](contributing_apub_api_outline.md).
diff --git a/docs/src/federation/resources.md b/docs/src/federation/resources.md
new file mode 100644
index 00000000..0f14691c
--- /dev/null
+++ b/docs/src/federation/resources.md
@@ -0,0 +1,22 @@
+# ActivityPub Resources
+
+## Official Documents
+
+- [ActivityPub standard](https://www.w3.org/TR/activitypub/)
+- [Activitypub vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/)
+
+## Explanations
+
+- [ActivityPub - one protocol to rule them all?](https://schub.io/blog/2018/02/01/activitypub-one-protocol-to-rule-them-all.html)
+- [A highly opinionated guide to learning about ActivityPub](https://tinysubversions.com/notes/reading-activitypub/)
+- [Activitypub implementers guide](https://socialhub.activitypub.rocks/t/draft-guide-for-new-activitypub-implementers/479)
+- [Mastodon Blog: How to implement a basic ActivityPub server](https://blog.joinmastodon.org/2018/06/how-to-implement-a-basic-activitypub-server/)
+- [Mastodon Blog: Implementing an ActivityPub inbox](https://blog.joinmastodon.org/2018/07/how-to-make-friends-and-verify-requests/)
+- [Data storage questions](https://socialhub.activitypub.rocks/t/data-storage-questions/579)
+- [Activitypub as it has been understood](https://flak.tedunangst.com/post/ActivityPub-as-it-has-been-understood)
+
+## Examples and Libraries
+
+- [ActivityPub example server](https://github.com/tOkeshu/activitypub-example)
+- [ActivityStreams crate](https://docs.rs/activitystreams/)
+- [HTTP Signatures crate](https://git.asonix.dog/Aardwolf/http-signature-normalization)
\ No newline at end of file