feat(docs): update docs design, add playground examples

.gitignore

@@ -4,6 +4,7 @@
 /.ng_compiled
 /.ng_build
 .lib
+docs/assets/examples/*
 
 # dependencies
 node_modules
@@ -34,6 +35,7 @@ testem.log
 /docs/framework
 /docs/docs.json
 /docs/output.json
+/docs/assets/examples
 
 # e2e
 /e2e/*.js

.stylelintrc.json

@@ -61,7 +61,9 @@
  "selector-pseudo-class-parentheses-space-inside": "never",
  "selector-pseudo-element-case": "lower",
  "selector-pseudo-element-colon-notation": "double",
- "selector-pseudo-element-no-unknown": true,
+ "selector-pseudo-element-no-unknown": [true, {
+ "ignorePseudoElements": ["ng-deep"]
+ }],
  "selector-type-case": "lower",
  "selector-max-id": 0,
 

DEV_DOCS.md

@@ -5,7 +5,7 @@
 - Use lifecycle interfaces
 - Use default angular view encapsulation
 - Use changeDetection: ChangeDetectionStrategy.OnPush where applicable
-- Never forget typedoc comments for public methods/properties
+- Never forget [document your changes add create some examples](#documentation)
 - Write tests
 - Create playground page per each new component/feature
 
@@ -38,16 +38,28 @@ We have to:
  - [x] use Angular CLI
 
 # Framework Structure
+- docs - Documentation and framework website built on top on the framework
 - src
- - app - Components playground, used for components development showcase, also covered with UI tests
- - docs - Documentation and framework website built on top on the framework
+ - app - runner app for components playground
+ - playground - independent module with runnable examples for each feature
  - backend - Small backend example
  - framework - Framework itself, divided into npm packages
  - theme - `@nebular/theme` npm package, main framework package
  - auth - `@nebular/auth` npm package, auth package (login, register, etc) 
  - icons - `nebular-icons` npm package, cool icons font
  - security - `@nebular/security` npm package, security framework package
 
+
+# Docs
+
+Docs is a separate Angular application located right in this project in `docs/` folder.
+The pages structure is taken from `structure.ts` file.
+The components documentation is take from the component comment sections.
+Runnable examples - an iframe to the same Angular application to a different route (/#/examples) where `playground module` is connected.
+In the build mode documentation and runnable examples are built in TWO separate apps and placed to `docs/dist` for the docs website
+and `docs/dist/run` for the examples. This is done so that we can reference an example in an iframe avoiding "same page iframe policy" which won't allow
+us to load the same page in the iframe on that page (and different pages starting only differentiated by `#something` are considered as one page in some
+browsers. 
 
 
 ## Auth // TODO 
@@ -154,9 +166,140 @@ Located in `theme/styles`
 TBD
 
 # Documentation
+
 Documentation is generated by the custom generator built on top of @nebular/theme.
+You have to use typedoc everywhere for the documentation purpose.
+
+## How to add page to the documentation
+
+Docs application splitted on the sections which you can find in the apps sidebar.
+Each section contains some pages.
+If you wanna add new page in the documentation, please, open `structure.ts`
+file in the root of docs application and add new page in the required section:
+
+```
+{
+ type: 'page',
+ name: 'Awesom page',
+ children: [
+ ... blocks
+ ],
+},
+```
+
+If it's completely new feature, maybe it would be better to create a new section:
+
+```
+{
+ type: 'section',
+ name: 'New super section',
+ children: [
+ ... pages
+ ],
+},
+```
+
+Page can contain multiple blocks of the following types:
+
+- [markdown](#markdown-block)
+- [component](#component-block)
+- [tabbed component](#tabbed-component-block)
+
+### Markdown block
+
+Renders plain markdown file from the `articles` dir.
+For example, if you wanna add getting started article you have to do the following:
+
+- put `getting-started.md` file in the `articles` folder.
+- add markdown block to the page children:
+
+```
+{
+ type: 'block',
+ block: 'markdown',
+ source: 'getting-started.md',
+},
+```
+
+### Component block
+
+If you have to render all the information about componend parsed with typedoc
+you have to use component blocks:
+
+```
+{
+ type: 'block',
+ block: 'component',
+ source: 'MyNewComponentName',
+},
+```
+
+### Tabbed component block
+
+Tabbed component block will render component description splitted on the following tabs:
+- Overview - This is typedoc comment above component
+- Theme - Theme variables listed in the typedoc comment above component with `@styles` tag, for example:
+
+```
+/**
+ * ...
+ *
+ * @styles
+ *
+ * var1
+ * var2
+ *
+ * ...
+ */
+```
+
+- API - parsing result of the typedoc above public methods and props
+- Examples - live examples listed in the typedoc comment above component
+
+## Examples
+
+When you're developing new funcitonality, please, always add some examples describing it.
+You have the following ways to add examples in your component documentation:
+- [Add raw code](#add-raw-code)
+- [Display inline examples from playground](#inline-examples)
+- [Render live examples from playground](#live-examples)
+- [Render stacked examples from palyground(live + inline)](#stacked-examples)
+
+### Add raw code
+
+If you wan't to describe small thing in two lines of code you can just add something similar in your typedoc comment:
+
+````
+```html
+<my-component></my-component>
+```
+````
+
+And don't forget specify language above your example.
+
+### Inline examples
+
+Inline example is an example file from our playground.
+Let's see how can we add inline example on the page:
+
+- Create example file in the playground folder. All files from playground folder will be coppied to the assets of the docs app.
+- Add `@inline-example(my-component/my-component.component.html)` somewhere in your typedoc comment.
+
+Also, if you wanna render all the component, not only one file from it, you can specify it's without file extension:
+`@inline-example(my-component/my-component.component)`
+in this case all the files with `my-component.component` name will be rendered.
+
+### Live examples
+
+Live example it's just playground page rendered in the iframe. So, to be able to use it
+you have to add example component in the playground and specify route for it.
+Then you need to pass this route name in `@live-example(my-super-route)` tag.
+
+### Stacked examples
 
-// TODO how to add a page to the documentation
+It's combination of the live and inline examples. When you add `@example(my-example)`
+in your typedoc comment, docs'll try to find component with name `my-example` and route with the same name and render them with switch.
+To give the user capability switch between live and inline representation of the example.
 
 # Release