docs docs (#150)

* docs docs

* changes

* a bit experimental

* bad idea

* all fixed

* and now corrected

Author: Noviny

README.md

@@ -1,14 +1,22 @@
 # Brisk Docs
 
-## A cute slogan goes here
+> Tools to document your mono-repos and React Packages
 
-TODO: Explain all this
+Brisk is an Atlassian Initiative to help with documenting code. It contains two main parts:
 
-## Getting running
+## [The Brisk Website Generator](./packages/website)
 
-```
-yarn global add bolt
-bolt
-```
+This is packaged as `@brisk-docs/website` and is designed as an all-inclusive documentation
+tool for mono-repos containing react components and other packages. Check out [its documentation](./packages/website)
+for more information on how to use it.
 
-This should install and link all the `node_modules`
+## Support Packages
+
+As part of being maximally useful, we want to make sure where possible, our helper components exist as
+their own packages. As such, there are a number of other libraries we maintain that you might be interested
+in, even if you don't need the complete set of things that brisk does:
+
+- [file viewer](./packages/file-viewer) - simple package to run a live component example alongside displaying its code
+- [react changelogs]('./packages/react-changelogs) - Component that accepts raw changelog files and formats them for display. Allows filtering to semver versions
+- [extract-react-types](https://extract-react-types.com/) - a way to extract and display types for components, works on both flow and typescript
+- [codesandboxer](https://github.com/codesandbox/codesandboxer) - Deploy a single file to codesandbox to make your code easy to share and collaborate on - can be used from node or from within a react app

docs.config.js

@@ -1,17 +1,23 @@
+const docs = [
+  {
+    path: './docs',
+    name: 'Docs',
+    description:
+      'Information about brisk as a whole, and contributing to brisk',
+  },
+];
+
+if (process.env && process.env.HEAD !== 'production') {
+  docs.push({
+    path: './example-pages',
+    name: 'Example Pages',
+    description: 'This is a collection of example pages for how pages ',
+  });
+}
+
 module.exports = () => ({
   siteName: 'Brisk Docs Docs',
   packages: ['./packages/*'],
   showSubExamples: true,
-  docs: [
-    {
-      path: './docs',
-      name: 'Docs',
-      description: 'View the documents for this project',
-    },
-    {
-      path: './guides',
-      name: 'Guides',
-      description: 'View the guides for this project',
-    },
-  ],
+  docs,
 });

docs/contributing.md

@@ -10,4 +10,3 @@ In a PR we expect:
 
 - tests to demonstrate your change.
 - a changeset to document your change (run `bolt changeset` and it will walk you through making a changeset). If you want to know more about changesets, read the documentation on our [release process](./release-process.md)
-

docs/getting-started.md

@@ -1,5 +1,7 @@
 # Getting started
 
+> This document is for deving on this mono-repo. For information on using brisk in your own project see the [@brisk-docs/website documentation](../packages/website)
+
 This project is a monorepo of several packages which can be managed using bolt.
 Before starting your work on any of the packages make sure you run:
 
@@ -20,14 +22,6 @@ bolt docs
 
 We use Jest for unit testing and Cypress for integration tests.
 
-To run unit tests across the entire project:
-
 ```sh
 bolt test
 ```
-
-or for a single package:
-
-```sh
-bolt w <package name> test
-```

guides/guide-1.md example-pages/guide-1.md

@@ -1,7 +1,7 @@
 # Brisk Docs website generator
 
 Brisk Docs is a package oriented documentation system that lets you write useful, interactive
-docs alongside your code.
+docs alongside your code. It is aimed at documenting packages in a mono-repo
 
 ## Getting started
 
@@ -11,16 +11,16 @@ Start by installing Brisk Docs in your project
 npm install @brisk-docs/website
 ```
 
-To start your docs website locally, simply run:
+To start your docs website locally:
 
 ```shell
 npm run brisk dev
 ```
 
-To produce a static build of the website that can be hosted:
+To produce a static build of the website that can be statically hosted:
 
 ```shell
-npm run brisk export:
+npm run brisk build && npm run brisk export:
 ```
 
 ## Organising your documentation
@@ -36,3 +36,24 @@ For guides and docs relating to your project or repository as a whole, Brisk Doc
 Brisk Docs has first class support for multi-package repos. All packages found in the `/packages` directory of your project will have documentation generated automatically.
 
 Read more about package documentation in our [package documentation guide.](./docs/writing-package-docs)
+
+## Using MDX
+
+MDX means that we parse markdown a little differently, and treat jsx blocks as react components.
+
+This means that you can write:
+
+```mdxjs
+# Just a regular markdown package
+
+import MyComponent from './src/myComponent'
+
+<MyComponent>I could not be expressed just with markdown<.MyComponent>
+
+Just some more _regular_ markdown here.
+```
+
+In addition to being able to render any markdown, brisk provides two components that can be used on any
+page without being imported.
+
+They are `<Props />` and `<FileViewer />` - these are exports of [pretty-proptypes](https://github.com/atlassian/extract-react-types/tree/master/packages/pretty-proptypes) and [file-viewer](../../packages/file-viewer)