The nexmo-developer gem provides a documentation platform ready to use with your custom documentation. This document will cover installation and usage instructions.

• Installation
• Usage
• Contributing
• License

You can use this gem from within your documentation.

To install the gem, create a Gemfile in the root folder of your documentation files and add the following inside it:

source "https://rubygems.pkg.github.com/nexmo" do
  gem "nexmo-developer"
end

Then, run bundle install from the command line. If this is your first time installing a gem from the GitHub Package Registry, follow these setup instructions.

This section will cover:

• File Organization
• Configuration and Customization
• Running the Gem

First, it is important that your documentation is organized in the way the gem expects.

The gem expects the documentation to be markdown files within the following folders:

+-- _open_api
+-- _use_cases
+-- _documentation
+-- _tutorials

In addition, the gem expects there to be two top-level required folders with configuration content, and a third top-level optional folder for public assets:

+-- config
+-- custom
+-- public

• The Configuration Files section will document the files required inside the /config folder.
• The Custom Views, Custom Landing Pages and Custom Locale Settings sections will document the files required inside the /custom folder.
• The Custom Public Assets section will document the files that can be included inside the /public folder.

• Configuration Files for the documentation portal are inside the /config folder.
• Custom Views can be provided inside the /custom/views folder.
• Custom Landing Pages can be provided inside the /custom/landing_pages folder.
• Custom Public Assets can be provided inside the /public folder.
• Custom Locale Settings can be provided inside the /custom/locales folder

Sample configuration files can be found inside the sample_config_files folder in this repository.

1. Business Information, including header and footer:

• Business information, including content for the header, can be customized through providing a business_info.yml configuration file inside the /config folder. The following is a sample business_info.yml configuration:

name: VBC
subtitle: Business for Developers
base_url: https://developer.vonage.com
assets:
  header_logo:
    path: '/images/logos/vbc-logo.png'
    alt: 'VBC Logo'
  footer_logo:
    path: '/images/logos/footer-logo.png'
    alt: 'VBC Footer Logo'
header:
  links:
    sign-up:
      path: https://developer.vonage.com
      text:
        - 'Log In'
        - 'Try Me'
  hiring:
    display: true # or false
footer:
  links:
    status:
      path: https://developer.vonage.com
      text: 'VBC Status' 
    navigation:
      documentation:
        - call-recording: 'https://vbc-developer.herokuapp.com/call-recording/overview'
        - provisioning: 'https://vbc-developer.herokuapp.com/provisioning/overview'
        - telephony: 'https://vbc-developer.herokuapp.com/telephony/overview'
        - reports: 'https://vbc-developer.herokuapp.com/reports/overview'
        - vonage-integration-platform: 'https://vbc-developer.herokuapp.com/vonage-integration-platform/overview'
        - smart-numbers: 'https://vbc-developer.herokuapp.com/smart-numbers/overview'
      api-reference:
        - call-recording: 'https://vbc-developer.herokuapp.com/api/call-recording'
        - provisioning: 'https://vbc-developer.herokuapp.com/api/provisioning'
        - telephony: 'https://vbc-developer.herokuapp.com/api/telephony'
        - reports: 'https://vbc-developer.herokuapp.com/api/reports'
        - vonage-integration-platform: 'https://vbc-developer.herokuapp.com/api/vonage-integration-platform'
      get-to-know-us:
        - vonage-business-communications: 'https://www.vonage.com/unified-communications/'
        - careers: 'https://www.vonage.com/corporate/careers/'
        - press: 'https://www.vonage.com/corporate'
    support:
      business-support: 'https://businesssupport.vonage.com/'
      developer-support: 'devsupport@vonage.com'

2. Top navigation bar:

• The links in the navigation bar can be customized through providing a top_navigation.yml configuration file inside the /config folder. In this file each navigation item should be provided on its own line in the following format: Name: /url. For example, Documentation: /documentation, is a valid entry. If a custom YAML file is not provided, the gem's default navigation bar will be rendered.

3. Header Meta Information:

• Meta-tags for the site must be provided inside a /config/meta_info.yml file. If the entries are not provided in this file, the site will not execute:

  title: # Title of your site for title bar
  description: # Description of site for search engines
  google-site-verification: # Verification code of site ownership for Google Search Console. *Will skip if not provided*
  application-name: # Name of application that the site represents

• The site expects the following meta icons and files to be placed inside the /public/meta folder. If they are not there, the site will raise an exception and not run (for examples of all of these files you can visit https://developer.nexmo.com/#{name of the file} to see an example):

  og.png
  apple-touch-icon.png
  favicon.ico
  favicon-32x32.png
  manifest.json
  safari-pinned-tab.svg
  mstile-144x144.png

4. Products Listing

Products are listed inside /config/products.yml. Each product must be listed with:

• icon, which is the name of the Volta icon to use, for example phone.
• icon_colour, the colour of the icon.
• path, which is the folder name inside the documentation where the product is listed. For example, call-recording for Call Recording.
• dropdown of either true or false, specifying if the product should be listed in the product dropdown menu listings inside Use Cases and Tutorials.

An example products.yml file:

products:
  - 
    name: 'Call Recording'
    icon: 'phone'
    icon_colour: 'blue'
    path: 'call-recording'
    dropdown: true
  - 
    name: 'Node RED'
    icon: 'flow'
    icon_colour: 'red'
    path: 'node-red'
    dropdown: true
  - 
    name: 'Provisioning'
    icon: 'phone'
    icon_colour: 'green'
    path: 'provisioning'
    dropdown: true
  - 
    name: 'Reports'
    icon: 'file-search'
    icon_colour: 'purple-dark'
    path: 'reports'
    dropdown: true
  - 
    name: 'Smart Numbers'
    icon: 'queue'
    icon_colour: 'yellow'
    path: 'smart-numbers'
    dropdown: true
  - 
    name: 'Telephony'
    icon: 'phone'
    icon_colour: 'black'
    path: 'telephony'
    dropdown: true
  - 
    name: 'Vonage Integration Platform'
    icon: 'chat'
    icon_colour: 'blue'
    path: 'vonage-integration-platform'
    dropdown: true
  - 
    name: 'Zapier'
    icon: 'lock'
    icon_colour: 'blue'
    path: 'zapier'
    dropdown: true
  - 
    name: 'Concepts'
    icon: 'message'
    icon_colour: 'green'
    path: 'concepts'
    dropdown: true
  - 
    name: 'App Center'
    icon: 'file-search'
    icon_colour: 'purple'
    path: 'app-center'
    dropdown: true

An example .env file can be found in this repository

Within your runtime production environment you can specify the following environment variables related to Google Analytics:

SEGMENT_WRITE_KEY
GOOGLE_ANALYTICS_TRACKING_ID
GOOGLE_TAG_MANAGER_ID
SEARCH_URL

You can also specify the following environment variable related to Hotjar analytics:

HOTJAR_ID

The following can be specified for Bugsnag analytics:

BUGSNAG_JS_API_KEY

For Algolia search specify the following environment variable:

ALGOLIA_APPLICATION_ID

A sample custom views folder can be found in this repository

All nexmo-developer static views can be redefined inside /custom/views by providing custom ERB files.

ERB, or embedded Ruby, are HTML files that combine Ruby to produce dynamic content.

The following ERB files can be provided to override the default views:

• /custom/views/static/landing.html.erb: The default home page
• /custom/views/layout/partials/_footer.html.erb: The footer
• /custom/views/layout/partials/_header.html.erb: The header
• /custom/views/layout/partials/_head.html.erb: The head file (meta tags, Google analytics info, and more)

A sample custom landing pages folder can be found in this repository

Customized landing pages is a powerful feature of the nexmo-developer gem that provides the ability to create unique content using only YAML files.

All custom landing page YAML files 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/tools.yml would be viewed at https://[YOUR WEBSITE URL]/tools.

Instructions for creating custom landing pages can be found here.

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:

<%= image_tag('/assets/media/logos/sample_image.png') %>

A sample custom locales folder can be found in this repository

Customized text to display for the menu and different display layouts can be provided inside the custom locale files. They are placed inside the /custom/locales folder in the documentation path. Each file is a YAML file named with the 2-letter abbreviation for the language, for example, English locale settings are placed inside /custom/locales/en.yml. The following is an example en.yml file showing custom text for the menu and for the site header:

en:
  menu:
    call-recording: Call Recording
    provisioning: Provisioning
    reports: Reports
    telephony: Telephony
    vonage-integration-platform: Vonage Integration Platform
    node-red: Node-RED
    zapier: Zapier
    extension: Extension
    user: User
    call: Call
    concepts: Concepts
    getting-started: Getting Started
    call_leg: Call Leg
    device_registration: Device Registration
    export-job: Export Job
    download: Download
    company-call-recording: Company Call Recording
    on-demand-call-recording: On-Demand Call Recording
    webhook: Webhook
    app-center: App Center
  layouts:
    partials:
      header:
        team: Team
        use-cases: Use Cases
        hiring: We're hiring

Once you have installed the gem and ran through the configurations, you can start it.

To start the gem run the following from the command line:

$ OAS_PATH=[PATH TO _open_api folder] RAILS_SERVE_STATIC_FILES=true RAILS_LOG_TO_STDOUT=true DISABLE_SSL=1 RACK_ENV=production RAILS_ENV=production 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:

$ OAS_PATH=/Users/sample_user/Documents/sample_docs/_open_api RAILS_SERVE_STATIC_FILES=true RAILS_LOG_TO_STDOUT=true DISABLE_SSL=1 RACK_ENV=production RAILS_ENV=production bundle exec nexmo-developer --docs=/Users/sample_user/Documents/sample_docs

Station is available as a Docker image at nemxodev/station. You can run it from your documentation directory using the following command:

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.

We ❤️ contributions from everyone! It is a good idea to talk to us first if you plan to add any new functionality. Otherwise, bug reports, bug fixes and feedback on the library is always appreciated. Look at the Contributor Guidelines for more information and please follow the GitHub Flow.

This library is released under the MIT License