(feat): more docs

docs/contributing/contributing.md

@@ -5,17 +5,18 @@ title: Contributing
 
 ## Working with Minds in GitLab
 
-The [Git/GitLab documentation](guides/git.md) explains our team workflow process and labelling guidelines. Make sure you are following these guidelines before you submit an issue or merge request.
+The [Git/GitLab documentation](guides/git.md) explains our team workflow process and labelling guidelines. Make sure you follow these guidelines before submitting an issue or merge request.
 
-## Submitting a Merge Request (MR)
+## Submitting a merge request (MR)
 
-We welcome community contributions to our open source code repositories. By signing a contributor license agreement (CLA), we ensure that the community is free to use your contributions.
+We welcome community contributions to our open-source code repositories. By signing a contributor license agreement (CLA), we ensure that the community is free to use your contributions.
 
-Before submitting an MR, make sure you have reviewed the [AGPLv3 license](contributing/license.md) and signed the <a href="https://na3.docusign.net/Member/PowerFormSigning.aspx?PowerFormId=e9c0907f-7056-403e-9972-0caad4ced5b6&env=na3-eu1&v=2">Minds Contributor License Agreement</a>.
+Before submitting an MR, make sure you have:
 
-> TODO: test CLA link
+1. Reviewed the [AGPLv3 license](contributing/license.md)
+2. Signed the <a href="https://na3.docusign.net/Member/PowerFormSigning.aspx?PowerFormId=e9c0907f-7056-403e-9972-0caad4ced5b6&env=na3-eu1&v=2"> Contributor License Agreement (CLA)</a>
 
-### Submitting an issue
+## Submitting an issue
 
 In most cases, issues submitted by the community will either be bugs or feature requests, submitted [here](https://gitlab.com/groups/minds/-/issues). If you have the required permissions, you can apply labels to a bug or feature yourself. If not, tag a [member of staff](https://gitlab.com/groups/minds/-/group_members) in a comment on the issue page (or post in the [Help & Support](https://www.minds.com/groups/profile/100000000000000681/feed) group) and we will take care of it as soon as possible.
 
@@ -23,11 +24,11 @@ In most cases, issues submitted by the community will either be bugs or feature
 
 - log a **feature request** to suggest we add something that doesn't already exist on the site. Be as descriptive as possible. We welcome mock-ups and even rough sketches in notebooks if they help illustrate your idea.
 
-### Earn token rewards for contributing
+## Earn token rewards for contributing
 
 Developers who find bugs or contribute code or documentation may qualify for Minds token rewards. All developer contributions will first be reviewed by the Minds staff to determine if they qualify for a reward.
 
-### More ways to contribute
+## Ways to contribute
 
 Looking for a project to get started? Check out:
 

docs/getting-started/introduction.md

@@ -4,14 +4,16 @@ title: Welcome to the Minds Stack
 sidebar_label: Introduction
 ---
 
-Minds is a free & open-source, encrypted and reward-based social networking platform. Our [Roadmap](https://gitlab.com/groups/minds/-/roadmap), [Code](https://gitlab.com/minds/minds), [Project Management System](https://gitlab.com/groups/minds/-/boards) and more all reside in [GitLab](https://gitlab.com/minds).
+Minds is a free & open-source, encrypted and reward-based social networking platform. Our [roadmap](https://gitlab.com/groups/minds/-/roadmap), [code](https://gitlab.com/minds/minds), [project management system](https://gitlab.com/groups/minds/-/boards), and more all reside in [GitLab](https://gitlab.com/minds).
 
 ## Security reports
+
 Please report all security issues to [security@minds.com](mailto:security@minds.com).
 
 ## License
+
 [AGPLv3](https://www.minds.org/docs/license.html). Please see the license file of each repository.
 
-___Copyright Minds 2012 - 2019___
+**_Copyright Minds 2012 - 2019_**
 
 Copyright for portions of Minds are held by [Elgg](http://elgg.org), 2013 as part of the [Elgg](http://elgg.org) project. All other copyright for Minds is held by Minds, Inc.

docs/guides/architecture.md

@@ -3,13 +3,16 @@ id: architecture
 title: Architecture
 ---
 
-> Mark will send diagram sketch
+> TODO update this diagram
+
+![Architecture diagram](assets/architecture-diagram.jpg "Diagram of Minds architecture")
+[Click to enlarge](assets/architecture-diagram.jpg)
 
 # Sockets
 
 Sockets are for live interactions, such as comments, group gathering pulsators, notifications, messenger, and the jury.
 
-Note: if you are using Docker, make sure your **JWT secret** maps to the **JWT secret** in `settings.php`. Kubernetes automatically maps it to the helm .yaml file.
+Note: if you are using Docker, make sure your **JWT secret** maps to the **JWT secret** in `settings.php`. You shouldn't have to do anything if you are using Kubernetes, which automatically maps it to the helm .yaml file.
 
 ```php
 $CONFIG->set('sockets-jwt-secret', '{{my-jwt-secret}}');

docs/guides/deployment.md

@@ -101,7 +101,7 @@ And add the values to the correponding yaml files:
 
 ## Why so many values and templating?
 
-Because it enables us to do something really cool, like dynamically override configuration values for your staging environment - useful for turning on your [feature flags](walk-throughs/feature-flags).
+Because it enables us to do something really cool, like dynamically override configuration values for your staging environment - useful for turning on your [feature flags](../walk-throughs/feature-flags).
 
 You can test your _local changes_ and manipulate the staging environments by using the helm-charts repo. Create your branch, make your changes and then, inside your helm-charts repository branch, run:
 

docs/guides/frontend.md

@@ -13,10 +13,13 @@ The source code can be found in the [front repository](https://gitlab.com/minds/
 
 ### Development
 
-From the front repository:
-`npm run build-dev`
+```console
+npm run build-dev
+```
+
+Keep this running while you are working so your changes will automatically be reflected when you refresh your browser.
 
-Keep this running while you are editing so your changes will automatically be reflected when you refresh your browser. Note that this doesn't apply to stylesheet changes - so when you're working with .scss files, you'll need to run `gulp build.sass` before you'll be able to see those changes.
+Note: this doesn't apply to stylesheet changes - so when you're working with .scss files, you'll need to run `gulp build.sass` before you'll be able to see those changes.
 
 ### Production
 
@@ -78,7 +81,7 @@ Minds follows the [BEM](http://getbem.com/naming/) naming conventions for elemen
 
 If you need to add a new class to an older file that has not yet been updated to use BEM conventions, add the new class twice: once with BEM, and again with whatever legacy convention the file is currently using.
 
-### Linting
+## Linting
 
 Minds uses [Prettier](https://prettier.io/) to enforce consistent formatting in frontend code.
 
@@ -122,4 +125,4 @@ _All_ colors should be defined using the `m-theme` mixin:
 }
 ```
 
-If something is black or white and you want it to _not_ change when the theme is changed (e.g. an overlay modal background should always be black, regardless of theme), use `$m-black-always` or `$m-white-always`.
+If something is black or white and you want to _not_ change it when the theme is changed (e.g. an overlay modal background should always be black, regardless of theme), use `$m-black-always` or `$m-white-always`.

docs/walk-throughs/cookies.md

----
-id: cookies
-title: Cookies
----
-
-> TODO: how to generate cookies

docs/walk-throughs/feature-flags.md

@@ -3,9 +3,9 @@ id: feature-flags
 title: Feature flags
 ---
 
-Feature flags allow new features to be introduced to a subset of users (i.e. those in Canary mode) before they are available to all users. Do this by enabling a feature flag and then wrapping a gate around code that you want to be executed for applicable users.
+Feature flags allow new features to be introduced to a subset of users (i.e. those in Canary mode) before they are available to all users. Start by enabling a feature flag and then wrap a gate around code that you want to be executed for applicable users.
 
-# Usage
+## Usage
 
 First, define and enable the flag in `settings.php`:
 
@@ -24,7 +24,7 @@ use Minds\Core\Features\Manager as FeaturesManager;
 
 ...
 
-$this->features = $features ?: new FeaturesManager;
+$this->features = new FeaturesManager;
 
 ...
 
@@ -34,7 +34,7 @@ if ($this->features->has('my-cool-feature')) {
 }
 ```
 
-In the frontend, import `FeaturesService`, add it to the constructor, and:
+It works similarly in the frontend. Import `FeaturesService`, add it to the constructor, and:
 
 ```ts
 if (this.featuresService.has('my-cool-feature')) {

docs/walk-throughs/infinite-scroll.md

@@ -3,4 +3,186 @@ id: infinite-scroll
 title: Infinite scroll
 ---
 
-> TODO: follow a cassandra response with paging token to the frontend
+The following walk-through covers how to limit the amount of list items returned in a repository response, set paging tokens on Cassandra responses, and connect the requests and responses with the frontend with the help of the infinite-scroll component.
+
+Let's say a user with a very popular channel wants to see a list of their subscribers. They have thousands of subscribers, and we only want to return 12 subscribers at a time because it would take a long time to return the entire list in one go (and their screen is only big enough to show <12 at one time subscribers anyway). As the user scrolls down their list of subscribers, we will continue populate the list by continually making requests for 12 more subscribers until they reach the end of the list.
+
+> TODO: proofread and annotate below
+
+### subscribers.component.ts
+
+```ts
+export class SubscribersComponent implements OnInit{
+ subscribers: Array<any> = [];
+ offset: string = '';
+ limit = 12;
+ moreData = true;
+ inProgress = false;
+ noInitResults = false;
+ fewerResultsThanLimit = false;
+
+ constructor(public client: Client) {}
+
+ ngOnInit() {
+ this.load(true);
+ }
+
+ load(initialLoad: boolean = false) {
+ if (this.inProgress) {
+ return;
+ }
+
+ this.inProgress = true;
+
+ if (initialLoad) {
+ this.subscribers = [];
+ this.moreData = true;
+ }
+
+ this.client
+ .get(`api/v2/subscribers`, { limit: this.limit, offset: this.offset })
+ .then((response: any) => {
+
+ // Hide infinite scroll's 'nothing more to load' notice
+ // if length of initial load is less than response limit
+ if (initialLoad && response.subscribers.length < this.limit) {
+ this.fewerResultsThanLimit = true;
+ this.moreData = false;
+ }
+
+ if (!response.subscribers.length) {
+ this.inProgress = false;
+ this.moreData = false;
+
+ // If no results on initial load, show notice instead of empty list
+ if (initialLoad) {
+ this.noInitResults = true;
+ }
+ return;
+ }
+
+ if (response['load-next']) {
+ this.offset = response['load-next'];
+ } else {
+ this.moreData = false;
+ }
+
+ this.subscribers.push(...response.subscribers);
+ this.inProgress = false;
+ })
+ .catch(e => {
+ this.moreData = false;
+ this.inProgress = false;
+ });
+ }
+```
+
+### subscribers.component.html
+
+```html
+<ng-container *ngFor="let subscriber of subscribers">
+ <div class="m-subscribers__subscriberContainer">
+ <div>{{subscriber.username}}</div>
+ </div>
+</ng-container>
+<div *ngIf="!fewerResultsThanLimit">
+ <infinite-scroll
+ distance="25%"
+ (load)="load()"
+ [moreData]="moreData"
+ [inProgress]="inProgress"
+ >
+ </infinite-scroll>
+</div>
+<div *ngIf="noInitResults">
+ <div>
+ You don't have any subscribers yet.
+ </div>
+</div>
+```
+
+### api/v2/subscribers.php
+
+```php
+public function get($pages)
+{
+ $response = [];
+
+ $limit = isset($_GET['limit']) ? $_GET['limit'] : 12;
+ $offset = isset($_GET['offset']) ? $_GET['offset'] : "";
+ $user_guid = isset($pages[0]) ? $pages[0] : Core\Session::getLoggedInUser()->guid;
+
+ $manager = Di::_()->get('Subscribers\Manager');
+
+ $opts = [
+ 'limit'=>$limit,
+ 'offset'=>$offset,
+ 'referrer_guid'=>$referrer_guid
+ ];
+
+ $subscribers = $manager->getList($opts);
+
+ $response['subscribers'] = Factory::exportable(array_values($subscribers->toArray()));
+ $response['load-next'] = (string) $subscribers->getPagingToken();
+
+ return Factory::response($response);
+}
+```
+
+### Subscribers/Manager.php
+
+```php
+public function getList($opts = [])
+{
+ $opts = array_merge([
+ 'limit' => 12,
+ 'offset' => '',
+ 'user_guid' => null,
+ ], $opts);
+
+ $response = $this->repository->getList($opts);
+
+ if ($opts['hydrate']) {
+ foreach ($response as $subscription) {
+ $subscriber = $this->entitiesBuilder->single($subscription->getSubscriberGuid());
+ $subscription->setProspect($subscriber);
+ }
+ }
+ return $response;
+}
+```
+
+### Subscribers/Repository.php
+
+```php
+use Minds\Common\Repository\Response;
+use Minds\Core\Data\Cassandra\Prepared;
+use Cassandra;
+class Repository
+{
+ public function getList($opts = [])
+ {
+ $opts = array_merge([
+ 'limit' => 12,
+ 'offset' => '',
+ 'user_guid' => null,
+ ], $opts);
+
+ $response = new Response;
+
+ $cqlOpts = [];
+ if ($opts['limit']) {
+ $cqlOpts['page_size'] = (int) $opts['limit'];
+ }
+
+ if ($opts['offset']) {
+ $cqlOpts['paging_state_token'] = base64_decode($opts['offset']);
+ }
+
+ $query = new Prepared\Custom();
+ $query->query($statement, $values);
+ $query->setOpts($cqlOpts);
+
+ }
+}
+```

website/i18n/en.json

@@ -43,7 +43,7 @@
  "title": "Sending emails"
  },
  "walk-throughs/feature-flags": {
- "title": "Feature Flags"
+ "title": "Feature flags"
  },
  "walk-throughs/infinite-scroll": {
  "title": "Infinite scroll"

website/sidebars.json

@@ -9,13 +9,11 @@
  "guides/frontend",
  "guides/backend",
  "guides/mobile",
- "guides/kubenetes",
  "guides/deployment",
  "guides/git"
  ],
  "Contributing": ["contributing/contributing", "contributing/license"],
  "Walk-throughs": [
- "walk-throughs/cookies",
  "walk-throughs/emails",
  "walk-throughs/feature-flags",
  "walk-throughs/infinite-scroll",

website/static/css/code-block-buttons.css

@@ -10,7 +10,7 @@ pre .btnIcon {
  cursor: pointer;
  border: 1px solid transparent;
  padding: 0;
- color: #999;
+ color: #bbb;
  background-color: transparent;
  height: 30px;
  transition: all 0.25s ease-out;
@@ -18,7 +18,7 @@ pre .btnIcon {
 
 pre .btnIcon:hover {
  text-decoration: none;
- color: #777;
+ color: #888;
 }
 
 .btnIcon__body {