docs: add setup docs, fix theming and faq

docs/content/advanced_theming.md

@@ -20,15 +20,15 @@ The background color uses a theme variable, but the hover color does not as ther
 
 ```js static
 const myTheme = {
-        colorBackground: 'white';
+  colorBackground: 'white';
 
   cssOverrides: {
-                MyComp: css\`
-                        &:hover {
-                                background-color: 'magenta';
-                        }
-                \`
-        }
+    MyComp: css`
+      &:hover {
+        background-color: 'magenta';
+      }
+    `
+  }
 }
 ```
 
@@ -75,14 +75,14 @@ There are two lines here to enable writing an override in the theme, either (a)
 
 ```js static
 const MyTheme = {
-        colorBackground: 'white',
+  colorBackground: 'white',
   colorPrimary: 'blue',
 
   cssOverrides: {
-        MyComp: css\`
-                        background: 'green'
-                \`
-  }
+    MyComp: css`
+      background: 'green';
+    `,
+  },
 }
 ```
 
@@ -90,16 +90,16 @@ In the case of (b), when part of a larger object, the theme is defined:
 
 ```js static
 const MyTheme = {
-        colorBackground: 'white',
+  colorBackground: 'white',
   colorPrimary: 'blue',
 
   cssOverrides: {
-        MyComp: {
-        Root: css\`
-                          background: 'green'
-                  \`
-    }
-  }
+    MyComp: {
+      Root: css`
+        background: 'green';
+      `,
+    },
+  },
 }
 ```
 
@@ -156,7 +156,7 @@ The `headingScale` function provides an easy way to conform to a heading scale d
 
 ```js static
 const MyTheme = {
-  fontSizeHeading4: \`${headingScale(12, 1.2, 4)}px\`   // evaluates to 17.28
+  fontSizeHeading4: `${headingScale(12, 1.2, 4)}px`, // evaluates to 17.28
 }
 ```
 

docs/content/faq.md

-# FAQ - Frequently Asked Questions
-
 This page documents snags, issues and problems experienced by developers of PubSweet apps. The aim is to then either fix or properly document the behaviour in order to streamline the experience for future contributors.
 
 Feel free to add your own questions – and answers if you have them.
@@ -14,7 +12,7 @@ Feel free to add your own questions – and answers if you have them.
 
 Check whether docker engine service is running or not. It's good to check this in case `docker-compose` can’t access it.
 
-```
+```bash
 $ sudo service docker status
 ● docker.service - Docker Application Container Engine
    Loaded: loaded (/lib/systemd/system/docker.service; enabled; vendor preset: enabled)
@@ -30,23 +28,23 @@ $ sudo service docker status
 
 Check Docker's unix socket file whether it has correct owner or not.
 
-```
+```bash
 $ sudo ls -la /var/run/docker.sock
 srw-rw---- 1 root docker 0 Dec 21 19:16 /var/run/docker.sock
 ```
 
 ## Is your user in docker's user group ?
 
-```
+```bash
 $ docker-compose up -d postgres
 ERROR: Couldn't connect to ˜Docker daemon at http+docker://localhost - is it running?
 ```
 
-You need to use sudo if your user is not in docker's user group. Even if you use sudo,  
-you may encounter other permission issues between host and container filesystems when you mounted volume to containers.  
+You need to use sudo if your user is not in docker's user group. Even if you use sudo,
+you may encounter other permission issues between host and container filesystems when you mounted volume to containers.
 You can add your user to docker user group with the following command.
 
-```
+```bash
 $ sudo usermod -aG docker ${USER}
 $ su - $USER
 ```
@@ -57,7 +55,7 @@ You should then logout and login into the host again.
 
 Sometimes we see problems like the following when trying to `setupdb` or start the application:
 
-```
+```bash
 $ pubsweet start
 info: Starting PubSweet app
 info: No "start" script defined in app. Falling back to "pubsweet server" behavior.
@@ -76,7 +74,7 @@ One of the following things might be happening:
 
 If `postgres` is running you should see the following by running: `docker ps`
 
-```
+```bash
 user@server:~$ docker ps
 CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
 a9db084764be        postgres            "docker-entrypoint..."   3 months ago        Up 2 months         0.0.0.0:5440->5432/tcp   a9db084764be_xpub_postgres_1
@@ -84,7 +82,7 @@ a9db084764be        postgres            "docker-entrypoint..."   3 months ago
 
 Otherwise start the postgres docker service by following the steps in the README file of the application. Probably it will be:
 
-```
+```bash
 $ yarn start:services
 ```
 
@@ -92,7 +90,7 @@ $ yarn start:services
 
 The default configuration is in the folder `config/default.js` of your app. Please, souble the check the guide in the README file of the project for the correct way of configuring your app. Also in the config folder you will find other files like `developement.js`, `test.js`. Those files overwrite the `default.js` configuration depending on the environment that you run your app in. This can be checked by running:
 
-```
+```bash
 user@server:~/Projects$ echo $NODE_ENV
 development
 ```
@@ -104,7 +102,7 @@ You can set your environment by performing `export NODE_ENV=development` that wi
 There are two ports that should be open. First one is the web app port which usually is 3000 - but this is configured from the config file of the application - and the second one is the database port (Postgres) which is usually 5432.
 Using `telnet` or `nc` tool we can check if these ports are open :
 
-```
+```bash
 $ nc -zv localhost 5432
 Ncat: Version 7.50 ( https://nmap.org/ncat )
 Ncat: Connected to ::1:5432.
@@ -113,13 +111,13 @@ Ncat: 0 bytes sent, 0 bytes received in 0.01 seconds.
 
 In case that fails we should open the ports from the firewall list, using ufw or iptables by performing the following command:
 
-```
+```bash
 ufw allow 5432
 ```
 
 or
 
-```
+```bash
 sudo iptables -A INPUT -p tcp -d 0/0 -s 0/0 --dport 3000 -j ACCEPT
 ```
 

docs/content/setup.md

+There are a number of ways of running the application in development.
+
+1. Hybrid - runs backing services with Docker but keeps the Node process on the host. Recommended for most developers.
+2. Docker - runs everything in Docker. Easiest to get started but has limitations.
+3. No Docker - doesn't require Docker. Requires a bit more up front set up.
+
+## Hybrid
+
+### Requirements
+
+- Node.JS >8.9
+- Docker
+
+### Setup
+
+```bash
+yarn
+yarn start:services
+# in another terminal
+yarn server
+# or for running tests (db has to be running)
+yarn test
+```
+
+### Explanation
+
+This the recommended way to develop PubSweet applications as it minimises system software dependencies and maximises flexibility.
+
+- `yarn` installs JavaScript dependencies
+- `yarn start:services` uses Docker Compose to start containers for the backing services (at present just the PostgreSQL database)
+- `yarn server` runs `pubsweet server` which does a number of things:
+  - set up the database if necessary, including a default user (with credentials `admin`/`password` by default)
+  - build client side application with Webpack
+  - start server application with Express
+
+## Full Docker
+
+### Requirements
+
+- Docker
+
+### Setup
+
+```bash
+docker-compose up
+# or `yarn start` if you have Node
+# or `pubsweet start` if you have PubSweet CLI
+```
+
+### Explanation
+
+This is the easiest way to get up and running after cloning a PubSweet application.
+
+Docker Compose does the following:
+
+- start containers for the backing services (database)
+- start a container and mount the code from the host into the it
+- run `yarn` in the container to install dependencies
+- run `pubsweet server` (see above for details of what this does)
+
+This setup has a number of drawbacks:
+
+- file watching and reloading is slower
+- harder to debug Node process
+- can't `npm link` dependencies outside of the project root
+- can lead to issues with file permissions
+
+## No Docker
+
+### Requirements
+
+- Node >8.9
+- PostgreSQL >9.6
+
+### Setup
+
+Start PostgreSQL server according to your OS, create a database and configure the connection details in the PubSweet application.
+
+```bash
+yarn
+yarn server
+```
+
+If you setup a user and password for you PostgreSQL database and you get an error like
+
+```bash
+error: error: password authentication failed for user ...
+```
+
+you can write the correct credentials in config/default.js, in `pubsweet-server.db` like so
+
+```js static
+    'pubsweet-server': {
+        db: {
+            user: ...,
+            password: ...,
+            // these are optional, in case you don't use default
+            host: ...,
+            database: ...,
+            port: ...
+        },
+```
+
+More information on the db javascript object [here](https://node-postgres.com/api/pool).
+
+### Explanation
+
+By installing PostgreSQL server natively on you machine, you remove the need for Docker but that requires a bit more up front configuration. See above for details of what the `server` command does.

docs/styleguide.config.js

@@ -102,6 +102,10 @@ module.exports = {
           name: 'How can I debug?',
           content: './content/how_can_i_debug.md',
         },
+        {
+          name: 'Setup',
+          content: './content/setup.md',
+        },
         {
           name: 'FAQ',
           content: './content/faq.md',
@@ -124,11 +128,11 @@ module.exports = {
           components: '../packages/ui/src/molecules/*.js',
         },
         {
-          name: 'Core-components',
-          components: '../packages/components/!(xpub-*|model-*)/**/*.{jsx,js}',
+          name: 'Core components',
+          components: '../packages/components/!(xpub-*|model-*)/**/*.{js,jsx}',
         },
         {
-          name: 'Xpub-components',
+          name: 'Xpub components',
           components: '../packages/components/xpub-*/**/*.{jsx,js}',
         },
       ],