Merge branch 'master' into public-access

README.md

@@ -4,71 +4,11 @@
 
 [![Build Status](https://travis-ci.com/dabapps/roe.svg?token=YbH3f6uroz5f5q8RxDdW&branch=master)](https://travis-ci.com/dabapps/roe)
 
-## Development
+## About
 
-Clone the repo and run the following to start all the watchers, and serve `docs/` with livereloading CSS.
+Roe is a project development kit developed by [DabApps](https://www.dabapps.com).
+It is a collection of React components, styles, mixins, and atomic CSS classes to aid with the development of web applications.
 
-```shell
-npm install
-npm start
-```
+## Documentation
 
-Or run the examples directory with livereloading
-
-```shell
-npm run budo
-```
-
-## Usage
-
-### Install
-
-You need to install Roe and its peer dependencies with npm. Npm should warn you if you haven't installed any peer dependencies.
-
-```shell
-npm i @dabapps/roe -SE
-```
-
-Note: `-SE` is shorthand for `--save` (to add to package.json) `--save-exact` (exact version).
-
-Install a specific version with
-
-```shell
-npm i @dabapps/[email protected] -SE
-```
-
-See [releases](https://github.com/dabapps/roe/releases) for a full list of versions.
-
-### Less
-
-Include Roe in your main `index.less` file. Do not use `../` in the path.
-
-```less
-@import 'node_modules/@dabapps/roe/src/less/index.less';
-```
-
-### Components
-
-All components are exported, named, at the root level.
-
-```javascript
-import {
-  Column,
-  Container,
-  Row
-} from '@dabapps/roe';
-```
-
-### Code Higlighting
-
-If you want to use the `CodeBlock` component with code highlighting you will need to include `highlight.js` in your index.html (or bundle the styles if you prefer, the javascript must be globally available).
-
-Highlight.js recommends this CDN.
-
-```html
-<!-- Include this in your head tag -->
-<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github-gist.min.css">
-
-<!-- Include this anywhere before your main javascript file -->
-<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
-```
+Full documentation, examples, and installation / contribution instructions can be found [here](http://dabapps.github.io/roe).

docs/introduction/about.md

@@ -0,0 +1,14 @@
+Roe is a project development kit developed by [DabApps](https://www.dabapps.com).
+It is a collection of React components, styles, mixins, and atomic CSS classes to aid with the development of web applications.
+
+Written with TypeScript and LESS, it has a fairly flexible API based around component composition, and does not assume anything about the projects' data storage solution, and thus can be integrated with any existing application (though, this may have naming conflicts, and therefore it is recommended that Roe only be used when creating an application from scratch).
+
+Roe takes inspiration from a lot of places, but primarily [Bootstrap](https://getbootstrap.com/). You will notice that Roe has a very similar grid system, naming convention for classes, etc.
+
+We decided to develop Roe for several major reasons:
+
+1. We use React for the majority of our frontend development, and alternatives to Roe either did not supply React components, were not as flexible as we required, or were immature (in terms of project life).
+
+2. By creating our own project development kit we allowed ourselves to have complete control over what components are available, how these components were implemented, and the level of polish applied (we had found in the past that some component libraries were so "complete" that they were hard to customize).
+
+3. As a company, DabApps have been using LESS as our CSS processor for many years, and most modern component libraries had migrated to either SASS or styles applied via javascript, such as JSS.

docs/introduction/contributing.md

@@ -0,0 +1,41 @@
+Fork [the repository](https://github.com/dabapps/roe) and run the following to install dependencies:
+
+```shell
+npm i
+```
+
+To start all the watchers (TypeScript, LESS, markdown files, etc), and serve the documentation with livereloading, run the following:
+
+```shell
+npm start
+```
+
+Or if you just want play around with some components without updating the documentation, you can run the `examples` directory with livereloading by running the following:
+
+```shell
+npm run budo
+```
+
+You can run all the type checking, linting and tests with the following:
+
+```shell
+npm test
+```
+
+To run the tests alone you can run:
+
+```shell
+npm run tests
+```
+
+And you can update test snapshots with:
+
+```shell
+npm run tests -- -u
+```
+
+To run prettier on all TypeScript files (enforced by the linting stage), run the following:
+
+```shell
+npm run prettier
+```

docs/introduction/description.md

@@ -0,0 +1,3 @@
+**DabApps' Project Development Kit**
+
+[![Build Status](https://travis-ci.com/dabapps/roe.svg?token=YbH3f6uroz5f5q8RxDdW&branch=master)](https://travis-ci.com/dabapps/roe)

docs/introduction/development-status.md

@@ -0,0 +1,13 @@
+### Releases
+
+Roe is currently not at a major release, and therefore changes to the API are expected on a reasonably regular basis. Changes to the minor version number at this stage signify potentially breaking changes, and changes to the patch number will include minor API changes as well as bug fixes.
+
+### Browser support
+
+Although Roe currently works in IE8+ (graceful degradation), support for IE8 (and possibly newer versions) may be dropped completely before the first major release.
+
+Note: none of the styles are vendor prefixed (e.g. with `-webkit-`), so in order to get the full browser support styles should be post-processed with [autoprefixer](https://github.com/postcss/autoprefixer).
+
+### Documentation
+
+As Roe has only been used internally by DabApps so far, the documentation may be lacking some information, but we will make an ongoing effort to improve this.

docs/introduction/getting-started.md

@@ -0,0 +1,58 @@
+### Less
+
+#### Import Roe styles
+
+Include Roe in your main `index.less` file. Do not use `./` or `../` in the path.
+
+```less
+@import 'node_modules/@dabapps/roe/src/less/index.less';
+```
+
+#### Initial styling
+
+A good place to start when customizing Roe, rather than layering styles on top of the existing ones, is to create a variables.less file, import this from your main LESS file, copy the variables from [the variables section of the documentation](#variables), and tweak them as desired.
+
+This will help avoid writing lots of custom LESS to override existing Roe styles, and there are a lot of existing variables to play around with.
+
+### Components
+
+All components are exported, named, at the root level.
+
+```javascript static
+import {
+  Column,
+  Container,
+  Row
+} from '@dabapps/roe';
+
+const App = () => (
+  <Container>
+    <Row>
+      <Column md={6}>
+        Column 1
+      </Column>
+      <Column md={6}>
+        Column 2
+      </Column>
+    </Row>
+  </Container>
+);
+```
+
+### Important structural components and classes
+
+You should read the [AppRoot section](#root) before beginning development of other components, as this highlights some important setup steps regarding the underlying structure of your app, to allow Roe to function correctly.
+
+### Code Highlighting
+
+If you want to use the `CodeBlock` component with code highlighting you will need to include `highlight.js` in your index.html (or bundle the styles if you prefer, but the javascript must be globally available).
+
+Highlight.js recommends this CDN.
+
+```html static
+<!-- Include this in your head tag -->
+<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/github-gist.min.css">
+
+<!-- Include this anywhere before your main javascript file -->
+<script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script>
+```

docs/introduction/installation.md

@@ -0,0 +1,17 @@
+Roe can be installed from npm using the following command:
+
+```shell
+npm i @dabapps/roe -S
+```
+
+Note: `-S` is shorthand for `--save` (to add Roe to your package.json)
+
+If you are using a version of npm that does not support package lock files, it's recommended that you pin Roe to a specific version to avoid breaking changes.
+
+To do so, run the following command:
+
+```shell
+npm i @dabapps/roe -SE
+```
+
+Note: `-SE` is shorthand for `--save-exact` (which will pin to a specific version of Roe in your package.json)

styleguide.config.js

@@ -4,6 +4,29 @@
 var fs = require('fs');
 var path = require('path');
 
+var introduction = [
+  {
+    name: 'About',
+    content: 'docs/introduction/about.md'
+  },
+  {
+    name: 'Development status',
+    content: 'docs/introduction/development-status.md'
+  },
+  {
+    name: 'Installation',
+    content: 'docs/introduction/installation.md'
+  },
+  {
+    name: 'Getting started',
+    content: 'docs/introduction/getting-started.md'
+  },
+  {
+    name: 'Contributing',
+    content: 'docs/introduction/contributing.md'
+  }
+];
+
 var components = [
   {
     name: 'App',
@@ -165,6 +188,11 @@ module.exports = {
     Logo: path.join(__dirname, 'docs/components/logo'),
   },
   sections: [
+    {
+      name: 'Introduction',
+      content: 'docs/introduction/description.md',
+      sections: introduction
+    },
     {
       name: 'Components',
       sections: components
@@ -187,10 +215,14 @@ module.exports = {
         overflow: 'auto'
       }
     },
+    Pre: {
+      pre: {
+        overflow: 'auto'
+      }
+    },
     Code: {
       code: {
         border: 'none',
-        display: 'block',
         margin: 0,
         padding: 0
       }