station 0.0.0 → 0.0.93

data/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2017-2020 Nexmo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Procfile

@@ -0,0 +1 @@
+web: lib/nexmo_developer/bin/initiate server --docs /app/__repo

data/README.md

@@ -1,20 +1,54 @@
-station
-=======
-
-Just a simple application framework skeleton thing.  I get tired of setting up
-plumbing for apps in Ruby when I'm not using Rails.
-
-Note on Patches/Pull Requests
------------------------------
-* Fork the project.
-* Make your feature addition or bug fix.
-* Add tests for it. This is important so I don't break it in a
-  future version unintentionally.
-* Commit, do not mess with rakefile, version, or history.
-  (if you want to have your own version, that is fine but bump version in a
-   commit by itself I can ignore when I pull)
-* Send me a pull request. Bonus points for topic branches.
-
-Copyright
----------
-Copyright (c) 2010 Brendan Baldwin. See LICENSE for details.
+# Station: The Nexmo Developer Gem
+
+[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md)
+![Actions Status](https://github.com/nexmo/nexmo-developer/workflows/CI/badge.svg)
+[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE.txt)
+
+Station provides a documentation platform ready to use with your custom documentation.
+
+The [documentation for Station](https://nexmo.github.io/station) covers detailed installation, setup and configuration instructions. Please refer to the documentation as the primary resource for getting started with Station.
+
+* [Documentation](https://nexmo.github.io/station)
+* [Troubleshooting](#troubleshooting)
+* [Contributing](#contributing)
+* [License](#license)
+
+## Troubleshooting
+
+<details>
+<summary>
+How do I add a database to a review application?
+</summary>
+
+In the Heroku review app that you'd like a database for, visit `More -> Run Console` then run the following command:
+
+```bash
+cd lib/nexmo_developer/ && bin/rails db:migrate
+```
+</details>
+
+<details>
+<summary>
+What do I do if I encounter the ActionView::Template::Error: Webpacker can't find application.js error?
+</summary>
+    
+From the command line execute the following from within the `lib/nexmo_developer` folder in Station changing the paths for your local file paths to the API specification and documentation files:
+
+```bash
+rm -rf public/packs &&  DOCS_BASE_PATH=/path/to/docs RAILS_SERVE_STATIC_FILES=1 DISABLE_SSL=1 RAILS_LOG_TO_STDOUT=1 OAS_PATH=/path/to/oas/specs RAILS_ENV=production bundle exec rails assets:precompile --trace
+```
+</details>
+
+
+## Contributing
+
+We :heart: contributions from everyone! It is a good idea to [talk to us](https://nexmo-community-invite.herokuapp.com/) first if you plan to add any new functionality. Otherwise, [bug reports](https://github.com/Nexmo/nexmo-developer/issues/), [bug fixes](https://github.com/Nexmo/nexmo-developer/pulls) and feedback on the library is always appreciated. Look at the [Contributor Guidelines](CONTRIBUTING.md) for more information and please follow the [GitHub Flow](https://guides.github.com/introduction/flow/index.html).
+
+## [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/dwyl/esta/issues) [![GitHub contributors](https://img.shields.io/github/contributors/Nexmo/nexmo-developer.svg)](https://GitHub.com/Nexmo/nexmo-developer/graphs/contributors/)
+
+## License
+
+This library is released under the [MIT License][LICENSE]
+
+[signup]: https://dashboard.nexmo.com/sign-up?utm_source=DEV_REL&utm_medium=github&utm_campaign=nexmo-developer
+[license]: LICENSE.txt

data/app.json

@@ -0,0 +1,24 @@
+{
+  "buildpacks": [
+    { "url": "https://github.com/Nexmo/heroku-buildpack-clone-repo.git" },
+    { "url": "heroku/nodejs" },
+    { "url": "https://github.com/negativetwelve/heroku-buildpack-subdir" },
+    { "url": "heroku/ruby" }
+  ],
+  "env": {
+    "GIT_REPO_URL": { "required": true }
+  },
+  "stack": "heroku-18",
+  "formation": {
+    "web": {
+      "quantity": 1,
+      "size": "free"
+    }
+  },
+  "addons": [
+    "heroku-postgresql:hobby-dev"
+  ],
+  "scripts": {
+    "postdeploy": "cd /app/lib/nexmo_developer && bin/rails db:migrate"
+  }
+}

data/babel.config.js

@@ -0,0 +1,74 @@
+module.exports = function(api) {
+  var validEnv = ['development', 'test', 'production', 'staging']
+  var currentEnv = api.env()
+  var isDevelopmentEnv = api.env('development')
+  var isStagingEnv = api.env('staging')
+  var isProductionEnv = api.env('production')
+  var isTestEnv = api.env('test')
+
+  if (!validEnv.includes(currentEnv)) {
+    throw new Error(
+      'Please specify a valid `NODE_ENV` or ' +
+        '`BABEL_ENV` environment variables. Valid values are "development", ' +
+        '"test", and "production". Instead, received: ' +
+        JSON.stringify(currentEnv) +
+        '.'
+    )
+  }
+
+  return {
+    presets: [
+      isTestEnv && [
+        require('@babel/preset-env').default,
+        {
+          targets: {
+            node: 'current'
+          }
+        }
+      ],
+      (isProductionEnv || isDevelopmentEnv || isStagingEnv) && [
+        require('@babel/preset-env').default,
+        {
+          forceAllTransforms: true,
+          modules: false,
+          targets: {
+            browsers: '> 1%',
+          },
+          exclude: ['transform-typeof-symbol']
+        }
+      ]
+    ].filter(Boolean),
+    plugins: [
+      require('babel-plugin-macros'),
+      require('@babel/plugin-syntax-dynamic-import').default,
+      isTestEnv && require('babel-plugin-dynamic-import-node'),
+      require('@babel/plugin-transform-destructuring').default,
+      [
+        require('@babel/plugin-proposal-class-properties').default,
+        {
+          loose: true,
+          spec: true
+        }
+      ],
+      [
+        require('@babel/plugin-proposal-object-rest-spread').default,
+        {
+          useBuiltIns: true
+        }
+      ],
+      [
+        require('@babel/plugin-transform-runtime').default,
+        {
+          helpers: false,
+          regenerator: true
+        }
+      ],
+      [
+        require('@babel/plugin-transform-regenerator').default,
+        {
+          async: false
+        }
+      ]
+    ].filter(Boolean)
+  }
+}

data/bin/nexmo-developer

@@ -0,0 +1,112 @@
+#!/usr/bin/env ruby
+require 'optparse'
+
+clear_cache = false
+rake_ci = false
+rake_smartling_download = false
+rake_smartling_upload = false
+
+options = {}
+docs_path = OptionParser.new do |opts|
+  opts.banner = "Usage: nexmo-developer --docs='/path/to/docs'"
+  opts.on("-d", "--docs=DOCS", "Specify path to documentation") do |v|
+    if Dir.exist?(v)
+      ENV['DOCS_BASE_PATH'] = v
+      ENV['OAS_PATH'] ||= "#{v}/_open_api/definitions"
+      puts "Documentation path: '#{v}' set successfully."
+    else
+      puts "Error: --docs parameter value must be equal to a directory containing documentation."
+      exit
+    end
+  end
+  opts.on("-h", "--help", "Prints help instructions") do
+    puts opts
+    exit
+  end
+  opts.on("--clear-cache", "Clear Rails cache") do
+    clear_cache = true
+  end
+  opts.on("--rake-ci", "Runs ci tasks") do
+    rake_ci = true
+  end
+  opts.on("--rake-smartling-download", "Runs Smartling download check") do
+    rake_smartling_download = true
+  end
+  opts.on("--rake-smartling-upload", "Runs Smartling upload process") do
+    rake_smartling_upload = true
+  end
+end.parse!
+
+$LOAD_PATH.unshift(File.expand_path('../lib/nexmo_developer', __dir__))
+APP_PATH = File.expand_path('../lib/nexmo_developer/config/application', __dir__)
+
+require 'rails/all'
+require 'activeadmin'
+require 'bootsnap'
+require 'bugsnag'
+require 'devise'
+require 'geocoder'
+require 'gravatar_image_tag'
+require 'greenhouse_io'
+require 'recaptcha'
+require 'split/dashboard'
+require 'listen'
+require 'inherited_resources'
+require 'msgpack'
+require 'pg'
+require 'coffee-rails'
+require 'octokit'
+require 'webpacker'
+require 'clipboard/rails'
+require 'gmaps4rails'
+require 'nexmo_markdown_renderer'
+require 'truncato'
+require 'puma'
+require 'barnes'
+require 'woothee'
+require 'algoliasearch'
+require 'rest-client'
+require 'chartkick'
+require 'groupdate'
+require 'terminal-table'
+require 'lograge'
+require 'jbuilder'
+require 'nokogiri'
+require 'colorize'
+require 'neatjson'
+require 'slack-notifier'
+require 'autoprefixer-rails'
+require 'titleize'
+require 'countries'
+require 'country_select'
+require 'smartling'
+require 'newrelic_rpm'
+require 'redis'
+require 'rake'
+
+require 'config/application'
+require 'rails/command'
+
+if clear_cache
+  puts "Clearing Rails cache..."
+  Rails::Command.invoke 'runner', ['Rails.cache.clear']
+end
+
+if rake_ci
+  puts 'Running Rake tasks...'
+  Rails.application.load_tasks
+  Rails::Command.invoke 'runner', ["Rake::Task['db:setup'].invoke"]
+  Rails::Command.invoke 'runner', ["Rake::Task['ci:all'].invoke"]
+elsif rake_smartling_download
+  puts 'Running Smartling download check...'
+  Rails.application.load_tasks
+  Rails::Command.invoke 'runner', ["Rake::Task['smartling:download'].invoke"]
+elsif rake_smartling_upload
+  puts 'Running Smartling upload process...'
+  Rails.application.load_tasks
+
+  frequency, *paths = ARGV
+  Rails::Command.invoke 'runner', ["Rake::Task['smartling:upload'].invoke(#{paths}, #{frequency})"]
+else
+  Rails::Command.invoke 'server'
+end

data/docs/Getting-Started.md

@@ -0,0 +1,39 @@
+---
+title: "Getting Started"
+permalink: /Getting-Started
+---
+
+# Contents
+
+1. [Dependencies](#dependencies)
+2. [Booting Up For the First Time](#booting-up-for-the-first-time)
+
+## Dependencies
+
+Station is a platform tool built with Ruby on Rails. All of its attendant dependencies are managed internally and require only itself to be included as a dependency for installation.
+
+Either within the top-level folder of the content to be served or in a separate folder structure create a `Gemfile` and include the following in it:
+
+```ruby
+source "https://rubygems.pkg.github.com/nexmo" do
+  gem "nexmo-developer"
+end
+```
+
+Station is hosted on the GitHub Package registry, and requires its own credentials to be added to your system to download the package from it. The GitHub Package Registry documentation includes [step-by-step instructions](https://help.github.com/en/packages/using-github-packages-with-your-projects-ecosystem/configuring-rubygems-for-use-with-github-packages) on setting up your system to authenticate to the registry if it is the first time downloading a package from the registry.
+
+Once the `Gemfile` is completed, Station can be downloaded and installed locally by executing `bundle install` from the command line. 
+
+## Booting Up For The First Time
+
+Station requires a certain defined file structure in the content file path provided to the CLI when booting it up. Please refer to the [How To Use](How-To-Use.md#configuration-files) page for detailed instructions. Without this file structure, Station will not run correctly.
+
+To start Station the following command can be executed from the command line, replacing `/content/path` with the absolute file path to your content:
+
+```bash
+$ bundle exec nexmo-developer --docs=/content/path
+```
+
+For troubleshooting diagnosis you can turn on logging output to the console by prepending `RAILS_LOG_TO_STDOUT=true` to the command. This can also be defined permanently in a dotenv file in the top-level folder of your content.
+
+Station is also available as a Docker image. Please refer to the [How To Use](How-To-Use.md#running-with-docker) page for instructions on booting it up with Docker.

data/docs/How-To-Use.md

@@ -0,0 +1,272 @@
+---
+title: "How To Use"
+permalink: /How-To-Use
+---
+
+# Contents
+
+1. [Content Structure and Files](#content-structure-and-files)
+    1. [File Organization](#file-organization)
+    2. [Configuration Files](#configuration-files)
+    3. [Customization Options](#customization-options)
+2. [Running Station](#running-station)
+    1. [Running Standalone](#running-standalone)
+    2. [Running With Docker](#running-with-docker)
+3. [Configuring the Feedback Widget](#configuring-the-feedback-widget)
+
+## Content Structure and Files
+
+Station requires the content served by the platform to be organized in a defined way. The platform will not start if the folder structure is not present in the content path provided during initialization.
+
+Additionally, Station offers a lot of opportunities to customize the platform for unique needs.
+
+This section will go through each of these areas.
+
+### File Organization
+
+Inside the top-level folder of the content there must be the following folders:
+
+```
++-- _use_cases
++-- _documentation
++-- _tutorials
++-- public
++-- config
+```
+
+If you wish to include API specification reference documents you should also include a `_open_api` folder in the top-level of your folder structure as well.
+
+### Configuration Files
+
+All configuration files are written in YAML. The [Official YAML Web Site](https://yaml.org/) provides instructions on YAML formatting and specifications.
+
+There are [same configuration files](https://github.com/Nexmo/station/blob/master/sample_config_files/config) provided in this repository that can be used to provide a template for the configuration files for your instance of Station.
+
+All configuration files are placed inside the `/config` folder.
+
+The files required are:
+
+* `business_info.yml`: Specific business/organizational information for the platform. This includes the platform name, the path to the header and footer logos, and more.
+* `top_navigation.yml`: The links for the top navigation bar of the platform. 
+* `meta_info.yml`: Information used to generate the links in the platform's `<head>` tags, such as search engine optimization details.
+* `products.yml`: A list of each product or item covered in the platform's content. The icon, documentation path and color schema for each product is also specified here.
+
+In addition to the above configuration files, Station also expects the following files to be created and placed inside the `/public/meta` path. These files are meta icons also used in the generation of the `<head>` content:
+
+* `og.png`
+* `apple-touch-icon.png`
+* `safari-pinned-tab.svg`
+* `mstile-144x144.png`
+* `favicon.ico`
+* `favicon-32x32.png`
+* `manifest.json`
+
+Specific credentials and identification information for different third-party services can be included in the platform by placing them inside a dotenv file in the top-leve folder of the content. There is a [sample .env file](https://github.com/Nexmo/station/blob/master/.env.example) provided in this repository.
+
+### Customization Options
+
+Station provides many opportunities to customize the presentation of the platform. This section will walk through each possibility.
+
+#### Custom Views
+
+Custom views can be provided that override the defaults in Station. A sample [custom views folder](https://github.com/Nexmo/station/blob/master/sample_config_files/custom/views) can be found in this repository.
+
+To provide your own custom view for a Station view place it inside `/custom/views`.
+
+The file should be an ERB file. ERB, or embedded Ruby, are HTML files that combine Ruby to product dynamic content. The [Ruby documentation](https://docs.ruby-lang.org/en/2.3.0/ERB.html) provides detailed instructions on how to write with ERB.
+
+#### Custom Landing Pages
+
+Landing Pages are a feature of Station that enables content creators to introduce unique website pages using only YAML to create the content.
+
+A [sample landing pages folder](https://github.com/Nexmo/station/blob/master/sample_config_files/custom/landing_pages) has been provided in this repository to offer examples.
+
+All landing pages should be placed inside `/custom/landing_pages`. The URL path is defined by the file path. For example, a file placed inside `/custom/landing_pages/events/myevent.yml` would be viewed in the browser at `https://example.com/events/myevent`.
+
+Detailed instructions are available in the [Contribution Guide](https://developer.nexmo.com/contribute/guides/landing-pages) on creating landing pages.
+
+#### Custom Public Path
+
+Custom assets, such as images and icons, can be provided in the `/public` folder. They then can be referenced inside custom views. For example, if the following image is added inside `/public/assets/media/logos/sample_image.png` then it could be referenced using ERB syntax as follows:
+
+```ruby
+<%= image_tag('/assets/media/logos/sample_image.png') %>
+```
+
+#### Custom Locale Settings
+
+Station supports internationalization for different spoken languages. Content translations can be provided inside the `/custom/locales` folder. A [sample locales folder](https://github.com/Nexmo/station/blob/master/sample_config_files/config/locales) has been provided inside Station with examples of locale configuration files.
+
+## Running Station
+
+Station can be run either standalone on your system or in Docker with the provided Docker image. 
+
+### Running Standalone
+
+Once you have installed Station and ran through the configurations, you can start it.
+
+To start the gem run the following from the command line:
+
+```bash
+$ OAS_PATH=[PATH TO _open_api folder] bundle exec nexmo-developer --docs=[PATH TO DOCUMENTATION]
+```
+
+For example, if your documentation is at `/Users/sample_user/Documents/sample_docs` and your `_open_api folder` is at `/Users/sample_user/Documents/sample_docs/_open_api` then you would start nexmo-developer with the following command:
+
+```bash
+$ OAS_PATH=/Users/sample_user/Documents/sample_docs/_open_api
+```
+
+The `OAS_PATH` environment variable passed in during runtime can also be provided in the dotenv file mentioned above in the instructions.
+
+### Running With Docker
+
+Station is available as a Docker image at `nemxodev/station`. You can run it from your documentation directory using the following command:
+
+```bash
+docker run -p 3000:3000 -v /path/to/docs:/docs -t nexmodev/station
+```
+
+Any functionality requiring a database (such as redirects or feedback) will not work using this method. For a docker-based setup that includes a database add the following `docker-compose.yml` file to your project:
+
+```
+version: "3"
+services:
+  db:
+    image: postgres
+    environment:
+      - POSTGRES_HOST_AUTH_METHOD=trust
+      - POSTGRES_USER=nexmo_developer
+      - POSTGRES_DB=nexmo_developer_production
+  web:
+    image: nexmodev/station:latest
+    volumes:
+      - .:/docs
+    ports:
+      - "3000:3000"
+    depends_on:
+      - db
+    environment:
+      - POSTGRES_HOST=db
+```
+
+After running `docker-compose up`, you will need to run `docker-compose run web bundle exec rake db:migrate` to initialise the database.
+
+## Configuring the Feedback Widget
+
+The Feedback Widget is a fully customizable, wizard-based approach to leaving feedback. You can configure it to accept feedback from users which is both useful and actionable.
+
+### Configuring the Feedback Widget
+
+The Feedback Widget configuration is YAML-based and can be found in the `config/feedback.yml` file in your documentation directory.
+
+> **Note**: The Feedback Widget only appears if this file is present.
+
+Configuration involves specifying the different "Questions" you want to ask and the "Steps" you want to take in response to the answers to those questions.
+
+The general format of this file is as follows:
+
+```yaml
+title: Thanks! We love feedback!
+paths:
+  - question: Your documentation is great!
+    sentiment: positive
+    steps: 
+      - title: We're glad you love our docs
+        type: textarea
+        content: |-
+          We're glad you found what you are looking for!
+        label: Is there anything we did particularly well?
+        placeholder: Please type your feedback here
+        image: "/assets/images/applause.png"
+  - question: There is a problem with the documentation
+    sentiment: negative
+    steps: 
+      - title: Thanks for letting us know!
+        type: radiogroup
+        questions:
+          - The documentation is missing information.
+          - The documentation is unclear.
+          - The documentation is incorrect.
+          - There is a broken link.
+      - title: What have we left out?
+        type: textarea
+        placeholder: Please tell us what's wrong?
+        email: true
+      - title: Thanks for letting us know
+        type: plain
+        content: |-
+          We have recorded your feedback. If you have left your email address, we'll be in touch!
+    - question: I need help!
+        - title: What do you need help with?
+          type: radiogroup
+          questions:
+          - My account/billing.
+          - The capabilities of the product.
+          - Something else.
+        - title: Let's get you some help!
+          type: fieldset
+          fields:
+          - type: input
+            name: firstName
+            label: First name
+          - type: input
+            name: lastName
+            label: Last name
+          - type: input
+            name: companyName
+            label: Company Name
+          - type: input
+            name: apiKey
+            label: API Key
+            hint: "(Hint: You can find this in your account dashboard)"
+          - type: textarea
+            name: feedback
+            label: 'Please tell us how we can help you:'
+            placeholder: Please leave feedback here
+        - title: Thank You!
+          type: plain
+          content: |-
+            We have recorded your feedback and will get back to you as soon as we
+            can.
+          image: "/assets/images/support.svg"          
+```
+
+### Anatomy of the configuration file
+
+#### Paths
+
+The `paths` property defines the different "routes" that users can take through the feedback widget. It contains a sequence of `question` objects.
+
+#### Question
+
+Each `question` object represents one choice on the front page of the wizard and drives the flow of the feedback from that point onwards. Each option is selectable using a radio button.
+
+For example, in the configuration shown above, the front page of the wizard would show a dialog that contains the following options in a radio group:
+
+```
+[ ] Your documentation is great!
+[ ] There is a problem with your documentation
+[ ] I need help
+```
+
+At the point the user selects an item in this group, the feedback configured in the `sentiment` property is recorded. This is either `positive`, `neutral`, or `negative`. After that, the flow through the feedback widget depends on what is configured in the `steps` for that `question`.
+
+#### Steps
+
+The `steps` property is a sequence of objects that specify the route through the wizard based on the main `question` selected. There can be one, or multiple, steps.
+
+Each step shows a new page of the dialog, which can be one of the following different types, depending on the `type` property:
+
+* `plain` - Plain text, as specified in the `content` property.
+* `textarea` - A text area where the user can provide further information. You can optionally specify `label` and `placeholder` text for this.
+* `radiogroup` - Radio buttons where you can ask for further clarification. Each option is defined in the `questions` sequence.
+* `fieldset` - A form containing `fields` that can capture whatever information you require from your users.
+
+Any step can capture the user's email address so that you can get back to them about the feedback they have left. To include this field, specify `email: true` for the step.
+
+### Persistence
+
+The feedback captured by the wizard is stored in the database at `[YOUR_SITE_URL]/admin/feedbacks`. The questions the user was asked and the responses they entered are also stored, so that the users' answers can be seen in the context of the questions you asked. So, if you change the wizard's configuration, the users' responses still make sense.
+
+