Add developer handbook

app/app.ts

@@ -20,6 +20,13 @@ const App = Application.extend({
                 ],
             },
         },
+        handbook: {
+            dependencies: {
+                services: [
+                    'router',
+                ],
+            },
+        },
     },
 });
 

app/router.ts

@@ -48,6 +48,7 @@ const Router = EmberRouter.extend({
 const {
     engines: {
         collections,
+        handbook,
     },
 } = config;
 
@@ -65,6 +66,9 @@ Router.map(function() {
     if (collections.enabled) {
         this.mount('collections');
     }
+    if (handbook.enabled) {
+        this.mount('handbook');
+    }
 
     /*
      * Guid Routing
@@ -92,8 +96,8 @@ Router.map(function() {
     this.route('resolve-guid', { path: '/:guid' });
 
     // Error routes
-    this.route('not-found', { path: '*path' });
     this.route('error-no-api', { path: '*no_api_path' });
+    this.route('not-found', { path: '*path' });
 });
 
 /* eslint-enable array-callback-return */

config/environment.d.ts

@@ -139,6 +139,12 @@ declare const config: {
         collections: {
             enabled: boolean;
         };
+        handbook: {
+            enabled: boolean;
+        };
+    };
+    'ember-cli-tailwind'?: {
+        shouldIncludeStyleguide: boolean,
     };
 };
 

config/environment.js

@@ -14,6 +14,7 @@ const {
     CLIENT_ID: clientId,
     ENABLED_LOCALES = 'en, en-US',
     COLLECTIONS_ENABLED = false,
+    HANDBOOK_ENABLED = false,
     FB_APP_ID,
     GIT_COMMIT: release,
     GOOGLE_ANALYTICS_ID,
@@ -192,6 +193,12 @@ module.exports = function(environment) {
             collections: {
                 enabled: COLLECTIONS_ENABLED,
             },
+            handbook: {
+                enabled: HANDBOOK_ENABLED,
+            },
+        },
+        'ember-cli-tailwind': {
+            shouldIncludeStyleguide: false,
         },
     };
 

ember-cli-build.js

@@ -11,7 +11,17 @@ function postProcess(content) {
 }
 
 module.exports = function(defaults) {
+    const config = defaults.project.config(EMBER_ENV);
+
     const app = new EmberApp(defaults, {
+        ace: {
+            modes: ['handlebars'],
+        },
+        addons: {
+            blacklist: [
+                'ember-cli-addon-docs',
+            ],
+        },
         'ember-bootstrap': {
             bootstrapVersion: 3,
             importBootstrapFont: true,
@@ -75,6 +85,17 @@ module.exports = function(defaults) {
         'ember-cli-babel': {
             includePolyfill: true,
         },
+
+        // Options for ember-code-snippets options, used in the dev handbook.
+        // Included here because ember-code-snippets always looks to the host app.
+        // TODO: figure out a way to put these in the engine's index.js
+        includeHighlightJS: false,
+        includeFileExtensionInSnippetNames: false,
+        snippetSearchPaths: ['lib/handbook/addon'],
+        snippetRegexes: {
+            begin: /{{#(?:docs-snippet|demo.example|demo.live-example)\sname=(?:"|')(\S+)(?:"|')/,
+            end: /{{\/(?:docs-snippet|demo.example|demo.live-example)}}/,
+        },
     });
 
     app.import('node_modules/dropzone/dist/dropzone.css');
@@ -87,6 +108,12 @@ module.exports = function(defaults) {
         test: 'vendor/ember/ember-template-compiler.js',
     });
 
+    if (config.engines.handbook.enabled) {
+        app.import('vendor/highlight.pack.js', {
+            using: [{ transformation: 'amd', as: 'highlight.js' }],
+        });
+    }
+
     const assets = [
         new Funnel('node_modules/@centerforopenscience/osf-style/img', {
             srcDir: '/',

lib/handbook/addon/application/template.hbs

@@ -0,0 +1,2 @@
+{{docs-header}}
+{{outlet}}

lib/handbook/addon/components/code-snippet/template.hbs

@@ -0,0 +1 @@
+{{source}}

lib/handbook/addon/docs/api/item/template.hbs

@@ -0,0 +1,7 @@
+{{#if model.isComponent}}
+    {{api/x-component component=model}}
+{{else if model.isClass}}
+    {{api/x-class class=model}}
+{{else}}
+    {{api/x-module module=model}}
+{{/if}}

lib/handbook/addon/docs/components/loading-indicator/demo-dark/template.hbs

@@ -0,0 +1,7 @@
+{{#docs-demo as |demo|}}
+    {{#demo.example name='loading-indicator.dark.hbs'}}
+        {{loading-indicator dark=true}}
+    {{/demo.example}}
+
+    {{demo.snippet 'loading-indicator.dark.hbs'}}
+{{/docs-demo}}

lib/handbook/addon/docs/components/loading-indicator/demo-default/styles.scss

@@ -0,0 +1,3 @@
+.dark-background {
+    background-color: #666;
+}

lib/handbook/addon/docs/components/loading-indicator/demo-default/template.hbs

@@ -0,0 +1,11 @@
+{{#docs-demo as |demo|}}
+    {{#demo.example}}
+        <div local-class='dark-background'>
+            {{! BEGIN-SNIPPET loading-indicator.default.hbs }}
+            {{loading-indicator}}
+            {{! END-SNIPPET }}
+        </div>
+    {{/demo.example}}
+
+    {{demo.snippet 'loading-indicator.default.hbs'}}
+{{/docs-demo}}

lib/handbook/addon/docs/components/loading-indicator/template.md

@@ -0,0 +1,9 @@
+# Loading Indicator
+
+This component indicates loading.
+
+## For dark backgrounds
+{{docs/components/loading-indicator/demo-default}}
+
+## For light backgrounds
+{{docs/components/loading-indicator/demo-dark}}

lib/handbook/addon/docs/contributing/template.md

@@ -0,0 +1,55 @@
+# How to Contribute
+
+Make a PR!
+
+To enable the handbook locally, add the following to your `ember-osf-web/config/local.js`:
+```js
+module.exports = {
+    HANDBOOK_ENABLED: true,
+};
+```
+
+## Adding a docs page
+These pages are nice, friendly markdown files that live in `lib/handbook/addon/docs/`.
+To add a new page:
+
+1. Add a route to `lib/handbook/addon/routes.js`:
+    ```js
+    this.route('docs', function() {
+        // ...
+        this.route('my-new-page');
+    }
+    ```
+1. Add a link to the sidebar nav in `lib/handbook/addon/docs/template.hbs`:
+    ```hbs
+    {{#docs-viewer as |viewer|}}
+        {{#viewer.nav project=model as |nav|}}
+            [...]
+            {{nav.item 'My new page' 'docs.my-new-page'}}
+        {{/viewer.nav}}
+    {{/docs-viewer}}
+    ```
+1. Let your thoughts fall into markdown at `lib/handbook/addon/docs/my-new-page/template.md`
+
+## Adding a component to the gallery
+Follow the steps above to add a markdown page for your component at
+`docs.components.my-component`, then use `{{docs-demo}}` to display your
+component next to the actual code used to render it.
+
+Check out the
+{{#link-to 'docs.components.loading-indicator'}}`{{loading-indicator}}` demo{{/link-to}}
+for a simple example.
+
+
+## Docs TODO
+- Fill out all the docs pages with useful info
+- Add more components to the component gallery
+- Improve auto-generated API reference
+    - Move to another section, a second link in the header
+    - Add `@ignore` to things that shouldn't be there
+    - Add docstrings to more stuff
+    - Fix import paths (`app/models/...` should be `ember-osf-web/models/...`)
+    - Component arguments aren't internal
+- Easy deployment to Github Pages
+- Fix bugs
+    - Intermittent error on rebuild?

lib/handbook/addon/docs/conventions/template.md

@@ -0,0 +1 @@
+# Coding Conventions

lib/handbook/addon/docs/dev-env/template.md

@@ -0,0 +1 @@
+# Dev Environment

lib/handbook/addon/docs/index/template.md

@@ -0,0 +1,3 @@
+# OSF Front-end Developer Handbook
+
+Yay new handbook!

lib/handbook/addon/docs/quickstart/template.md

@@ -0,0 +1,3 @@
+# Quickstart
+
+First, create the universe.

lib/handbook/addon/docs/resources/template.md

@@ -0,0 +1 @@
+# Additional Resources

lib/handbook/addon/docs/route.js

@@ -0,0 +1,7 @@
+import Route from '@ember/routing/route';
+
+export default class DocsRoute extends Route {
+    model() {
+        return this.store.findRecord('project', 'osf-components');
+    }
+}

lib/handbook/addon/docs/styles.scss

@@ -0,0 +1,3 @@
+pre {
+    border: 0;
+}

lib/handbook/addon/docs/template.hbs

@@ -0,0 +1,29 @@
+{{#docs-viewer as |viewer|}}
+    {{#viewer.nav project=model as |nav|}}
+        {{nav.section 'Introduction'}}
+        {{nav.item 'What is this handbook?' 'docs.index'}}
+        {{nav.item 'How to contribute' 'docs.contributing'}}
+
+        {{nav.section 'Development'}}
+        {{nav.item 'Quickstart' 'docs.quickstart'}}
+        {{nav.item 'Dev environment' 'docs.dev-env'}}
+        {{nav.item 'Coding conventions' 'docs.conventions'}}
+        {{nav.item 'Testing' 'docs.testing'}}
+        {{nav.item 'Additional resources' 'docs.resources'}}
+
+        {{nav.section 'Component gallery'}}
+        {{nav.item 'Loading indicator' 'docs.components.loading-indicator'}}
+
+        {{nav.section 'Style guide'}}
+        {{nav.item 'Visual style' 'docs.visual-style'}}
+        {{nav.item 'Written style' 'docs.written-style'}}
+    {{/viewer.nav}}
+
+    {{#viewer.main}}
+        <div class="docs-container">
+            <div class="docs-section">
+                {{outlet}}
+            </div>
+        </div>
+    {{/viewer.main}}
+{{/docs-viewer}}

lib/handbook/addon/docs/testing/template.md

@@ -0,0 +1 @@
+# Testing

lib/handbook/addon/docs/visual-style/template.md

@@ -0,0 +1 @@
+# Visual Style

lib/handbook/addon/docs/written-style/template.md

@@ -0,0 +1 @@
+# Written Style

lib/handbook/addon/engine.js

@@ -0,0 +1,23 @@
+import Engine from 'ember-engines/engine';
+import loadInitializers from 'ember-load-initializers';
+import config from './config/environment';
+import Resolver from './resolver';
+
+const { modulePrefix } = config;
+
+const Eng = Engine.extend({
+    modulePrefix,
+    Resolver,
+    dependencies: {
+        services: [
+            'router',
+        ],
+    },
+
+    // HACK: ec-tailwind (used by ec-addon-docs) doesn't understand engines
+    rootElement: 'body',
+});
+
+loadInitializers(Eng, modulePrefix);
+
+export default Eng;

lib/handbook/addon/index/styles.scss

@@ -0,0 +1,4 @@
+.Link {
+    display: flex;
+    justify-content: center;
+}

lib/handbook/addon/index/template.hbs

@@ -0,0 +1,10 @@
+{{docs-hero
+    logo='ember'
+    slimHeading='OSF'
+    strongHeading='Web'
+    byline='Front-end Developer Handbook'
+}}
+
+<div local-class='Link'>
+    {{#link-to 'docs' class='btn btn-primary'}}Begin!{{/link-to}}
+</div>

lib/handbook/addon/resolver.js

@@ -0,0 +1,3 @@
+import Resolver from 'ember-resolver';
+
+export default Resolver;

lib/handbook/addon/routes.js

@@ -0,0 +1,32 @@
+import buildRoutes from 'ember-engines/routes';
+
+export default buildRoutes(function() {
+    this.route('docs', function() {
+        this.route('intro');
+        this.route('assumptions');
+        this.route('contributing');
+
+        // Dev
+        this.route('quickstart');
+        this.route('git');
+        this.route('dev-env');
+        this.route('conventions');
+        this.route('testing');
+        this.route('community');
+        this.route('resources');
+
+        // Style guide
+        this.route('visual-style');
+        this.route('written-style');
+
+        this.route('components', function() {
+            this.route('loading-indicator');
+        });
+
+        this.route('api', function() {
+            this.route('item', { path: '/*path' });
+        });
+    });
+
+    this.route('not-found', { path: '/*path' });
+});

lib/handbook/config/addon-docs.js

@@ -0,0 +1,4 @@
+const AddonDocsConfig = require('ember-cli-addon-docs/lib/config');
+
+module.exports = class extends AddonDocsConfig {
+};