Merge pull request #23 from paritytech/documentation

Documentation

.gitignore

@@ -22,4 +22,7 @@ src/client/stores/__import-stores.tsx
 src/client/components/__import-components.tsx
 
 yalc.lock
-.yalc
+.yalc
+
+documentation/.next/
+documentation/node_modules/

config-demo/application-3col-sample.json

@@ -7,7 +7,7 @@
  "mobile": {
  "fixed": [
  ["users", "NewjoinerDetector"],
- ["users", "NewjoinerDetector"]
+ ["users", "UserStatus"]
  ],
  "office": [
  [

documentation/next.config.js

@@ -0,0 +1,6 @@
+const withNextra = require('nextra')({
+ theme: 'nextra-theme-docs',
+ themeConfig: './theme.config.jsx'
+ })
+
+ module.exports = withNextra()

documentation/package.json

@@ -0,0 +1,20 @@
+{
+ "name": "documentation",
+ "version": "1.0.0",
+ "description": "",
+ "main": "index.js",
+ "devDependencies": {},
+ "scripts": {
+ "dev": "next",
+ "build": "next build",
+ "start": "next start"
+ },
+ "keywords": [],
+ "author": "",
+ "license": "ISC",
+ "dependencies": {
+ "next": "^14.1.4",
+ "nextra": "^2.13.4",
+ "nextra-theme-docs": "^2.13.4"
+ }
+}

documentation/pages/_meta.json

@@ -0,0 +1,7 @@
+{
+ "index": "Hub App Documentation",
+ "quickStart": "Quick start",
+ "framework": "Framework",
+ "modules": "Modules",
+ "commonErrors": "Common errors"
+}

documentation/pages/commonErrors.md

@@ -0,0 +1,2 @@
+## Common errors/issues
+

documentation/pages/development.md

@@ -0,0 +1,3 @@
+# Development
+
+TBA

documentation/pages/development/create-a-module.md

@@ -0,0 +1,3 @@
+# Create a module
+
+TBA

documentation/pages/development/new-route.md

@@ -0,0 +1,11 @@
+# How to create a new route
+
+1. Open the router.ts file of your module. If you haven't created your module yet see [Create a module Guide](./create-a-module.md)
+
+2. There are 3 types of routes that can be created.
+
+ publicApi - `/public-api/{module-name}/`
+
+ userApi - `/user-api/{module-name}/`
+
+ adminApi - `/admin-api/{module-name}/`

documentation/pages/framework/authentication.md

@@ -0,0 +1,41 @@
+# Authentication
+
+Authentication providers are defined in `application.json` under `auth.providers`. The default provider is `polkadot`. You can also turn on `google` auth provider and specify roles according to your domain.
+
+## Polkadot authentication
+
+Users can register with their polkadot addresses.
+
+To activate polkadot authentication you modify `application.json` by adding `polkadot` in the list of auth providers. E.g.
+
+```json
+ "auth": {
+ "providers": ["google", "polkadot"]
+ },
+```
+
+Set `AUTH_MESSAGE_TO_SIGN` to a random string. It is used for users to verify that they are the owners of the wallet they are logging in with.
+
+### Wallet Connect
+
+Wallet Connect allows your users to log in using their mobile devices. It is advisable to turn this feature on. In order to activate Wallet Connect integration you have to provide `WALLET_CONNECT_PROJECT_ID` in your `.env` file.
+
+Feel free to modify `AUTH_MESSAGE_TO_SIGN` to be any string you prefer instead of a random default string.
+
+## Google authentication
+
+Users can register using Google SSO. An automatic role can be configured and given based on the email domains users are registering with.
+
+### Activate
+
+Google callback: `http://<your-appHost>/auth/google/callback`
+
+Configure a Google project, and populate `OAUTH2_GOOGLE_CLIENT_ID` and `OAUTH2_GOOGLE_CLIENT_SECRET` with generated values. See [this guide for reference](https://developers.google.com/identity/oauth2/web/guides/get-google-api-clientid)
+
+To activate google authentication you modify `application.json` by adding `google` in the list of auth providers. E.g.
+
+```json
+ "auth": {
+ "providers": ["google", "polkadot"]
+ },
+```

documentation/pages/framework/configuration.md

@@ -0,0 +1,23 @@
+# Configuration
+
+Configuration for the project lives in a `./config` directory. We suggest keeping that directory in a separate repository and create symbolic link it for local development. You can find a sample folder called `config-demo` [here](https://github.com/paritytech/polkadot-hub-app/tree/master/config-demo)
+
+```
+./config
+├── application.json app name, auth, and homepage layout
+├── company.json company name, offices, departments, divisions
+├── modules.json list of enabled modules with their metadata and enabled integrations
+├── permissions.json list of roles with their permissions, default role by email domain
+├── modules custom modules
+│ ├── division-sync
+│ ├── help-center
+├── public custom static files
+│ ├── manifest.webmanifest custom manifest (as it can contain custom app name, icons set, etc)
+│ ├── images
+│ │ └── ...
+└── templates custom text templates
+ ├── guest-invites
+ │ └── email.yaml
+ └── visits
+ └── notification.yaml
+```

documentation/pages/framework/configuration/application.md

@@ -0,0 +1,177 @@
+# Application.json
+
+This file configures how modules are displayed on the screen.
+You can set different module placement for mobile and for desktop. Tablet view will follow the desktop configuration.
+
+Authentication providers are also defined here under `auth.providers`. The default provider is `polkadot`. You can also turn on `google` auth provider and specify roles according to your domain.
+
+### Application configuration sample
+
+```json
+{
+ "name": <Your-app-name>,
+ "auth": {
+ "providers": ["polkadot"]
+ },
+ "layout": {
+ "mobile": {
+ "fixed": [
+ ["users", "NewjoinerDetector"],
+ ["users", "UserStatus"]
+ ],
+ "office": [
+ ["events", "UncompletedActions"],
+ ["events", "MyEvents"],
+ ["quick-navigation", "QuickNav"],
+ ["users", "UsersMapWidget", { "offices": ["global"] }],
+ ["about", "AboutWidget", { "offices": ["berlin", "lisbon", "london"] }]
+ ],
+ "events": [["events", "UpcomingEvents"]],
+ "news": [["news", "LatestNews"]]
+ },
+ "desktop": {
+ "sidebar": [
+ ["quick-navigation", "QuickNav"],
+ ["about", "AboutWidget", { "offices": ["berlin", "lisbon", "london"] }]
+ ],
+ "main": [
+ [
+ [
+ "office-visits",
+ "Actions",
+ { "offices": ["berlin", "lisbon", "london"] }
+ ]
+ ],
+ [["announcements", "Announcement"]],
+ [["users", "UsersMapWidget", { "offices": ["global"] }]],
+ [
+ ["events", "UpcomingEvents"],
+ ["news", "LatestNews"]
+ ]
+ ]
+ }
+ }
+}
+
+```
+
+## Mobile
+
+```json
+ "mobile": {
+ "fixed": [
+ ["users", "NewjoinerDetector"],
+ ["users", "UserStatus"]
+ ],
+ "office": [
+ ["events", "UncompletedActions"],
+ ["events", "MyEvents"],
+ ["quick-navigation", "QuickNav"],
+ ["users", "UsersMapWidget", { "offices": ["global"] }],
+ ["about", "AboutWidget", { "offices": ["berlin", "lisbon", "london"] }]
+ ],
+ "events": [["events", "UpcomingEvents"]],
+ "news": [["news", "LatestNews"]]
+ },
+```
+
+`fixed` - items above the call to action widget (Visit office, Book a Room, Invite a Guest)
+
+`office`, `events`, `news` tabs are configurable.
+
+<div style="display: flex; column-gap: 10px; align-items: flex-end">
+<Image
+ src="/mobileOffice.png"
+ alt="mobile office"
+ width="250"
+ height="200"
+ style="border: 1px solid lightGray; border-radius: 10px; margin-top: 10px"
+/>
+
+<Image
+ src="/mobileEvents.png"
+ alt="mobile events"
+ width="250"
+ height="200"
+ style="border: 1px solid lightGray; border-radius: 10px; margin-top: 10px"
+/>
+
+<Image
+ src="/mobileNews.png"
+ alt="mobile news"
+ width="250"
+ height="200"
+ style="border: 1px solid lightGray; border-radius: 10px; margin-top: 10px"
+/>
+
+</div>
+
+## Desktop
+
+```json
+ "desktop": {
+ "sidebar": [
+ ["quick-navigation", "QuickNav"],
+ ["about", "AboutWidget", { "offices": ["berlin", "lisbon", "london"] }]
+ ],
+ "main": [
+ [
+ [
+ "office-visits",
+ "Actions",
+ { "offices": ["berlin", "lisbon", "london"] }
+ ]
+ ],
+ [["announcements", "Announcement"]],
+ [["users", "UsersMapWidget", { "offices": ["global"] }]],
+ [
+ ["events", "UpcomingEvents"],
+ ["news", "LatestNews"]
+ ]
+ ],
+ "sidebarRight": [
+ ["events", "MyEvents"],
+ ["events", "UpcomingEvents"],
+ ["news", "LatestNews"]
+ ]
+ }
+
+```
+
+<Image
+ src="/desktopLayout.png"
+ alt="desktop layout"
+ style="border: 1px solid lightGray; border-radius: 10px; margin-top: 10px"
+/>
+You can choose between 3 and 2 column layout.
+
+### 3 col layout
+
+In order to configure 3 columns populate `sidebar`, `main` and `sidebarRight` with your configuration.
+
+<Image src="/layout-3col.png" alt="Layout-3" width={600} height={650} />
+
+### 2 col layout
+
+For the 2 column layout populate `sidebar` and `main` only.
+<Image src="/layout-2col.png" alt="Layout-2" width={600} height={650} />
+
+### Widget configuration
+
+```
+["users", "UsersMapWidget", { "offices": ["global"] }],
+```
+
+This configuration only shows widget `UsersMapWidget` from the `users` module in the office with id `global`
+
+```
+["news", "LatestNews"]
+```
+
+Widget `LatestNews` from module `news` is displayed in all hubs.
+
+```
+["about", "AboutWidget", { "offices": ["berlin", "lisbon", "london"] }]
+```
+
+Widget `AboutWidget` from module `about` is displayed in `berlin`, `lisbon` and `london` hubs.