station 0.0.0 → 0.0.93

data/lib/nexmo_developer/app/views/contribute/structure/content-types/guides.md

@@ -0,0 +1,14 @@
+---
+title: Guides
+navigation_weight: 2
+---
+
+# Guides
+
+The Guides provide information on the key concepts associated with a product.
+
+Ideally the Guide should also point to further useful resources such as:
+
+* Code Snippets - Guides may link to Code Snippets to show specific implementation details.
+* Use Cases - Step-by-step instructions to solve specific use cases with the Nexmo APIs.
+* API Reference - Full details of the API's functionality.

data/lib/nexmo_developer/app/views/contribute/structure/content-types/overviews.md

@@ -0,0 +1,34 @@
+---
+title: Overviews
+navigation_weight: 1
+---
+
+# Overviews
+
+Overview pages are the first pages you reach when you select a product. They serve to support the user to understand the product and direct them to the most appropriate resources.
+
+## Opening
+
+Explain what the product is and with bullet points what you can do with the product.
+
+> Note: The opening has no heading as the `Overview` heading serves this purpose.
+
+## Contents
+
+This should be a bulleted outline of the contents of the current page, each item should be an anchor link to a page heading.
+
+## Concepts
+
+It's important to make sure that the user has a grasp of subjects that are common throughout the product you are documenting. Concepts introduces these in brief and links off to further reading where appropriate. Concepts will usually be described in more detail in the Guides.
+
+## Getting started
+
+This section is designed to prove to the user the product does what it claims to. This could be an interactive demonstration or an opinionated and basic getting started guide.
+
+## Features
+
+Now that the user has an understanding of what the product does, it's important to tell them what the capabilities of the product are. Also add links to the guides here.
+
+## Further reading
+
+Further reading isn't a section itself but rather contains links off to the product Code Snippets, Guides, API References and Tutorials.

data/lib/nexmo_developer/app/views/contribute/structure/content-types/tutorials.md

@@ -0,0 +1,59 @@
+---
+title: Tutorials
+navigation_weight: 4
+---
+
+# Tutorials
+
+A tutorial is a complete walkthrough of how to build something practical. It is  step-by-step and self-contained example, providing all the necessary content inline and focused on a single, well-defined outcome. Tutorials support multiple programming languages, if that's what you need.
+
+> **Note**: Please read our [Tutorials and Use Cases guide](/contribute/guides/tutorials-and-use-cases) to help you decide whether a tutorial is the best fit for your content.
+
+The following screenshot illustrates the appearance of a tutorial:
+
+![Sending a message with Dispatch API](/assets/images/contributing/task-example.png)
+
+
+
+## Opening
+
+Explain what the problem is and outline the steps that you'll take to overcome it in bullet points.
+
+> Note: The opening has no heading as the heading should serve this purpose.
+
+## Guide
+
+Every tutorial has its own problem to solve. Use headings and sections that align with the steps one would take to overcome the problem.
+
+## Conclusion
+
+Reflect on:
+
+* What you have done
+* How you could extend on what you have learnt
+
+Point to resources:
+
+* Guides - Guides covering the concepts used in the tutorial.
+* Code Snippets - cover specific bits of code to do single function operations.
+* API Reference - Given that the tutorial is opinionated, provide this as a resource to allow the user to see what other options are available to them.
+* Tutorials - Other relevant tutorials.
+
+## External Tutorials
+
+We can include tutorial entries for content that is actually elsewhere, such as on the blog. This is useful for bringing Tutorial Tuesday content and X with Y posts into the developer portal so that users can find other content that may be of interest.
+
+To create an external tutorial, create a markdown file with _just_ frontmatter. It should look something like this:
+
+```
+---
+title: Anything-to-SMS with IFTTT and Nexmo
+products: messaging/sms
+description: This is a description that will be shown on the tutorials list page
+external_link: https://www.nexmo.com/blog/2018/09/18/anything-to-sms-ifttt-nexmo-dr/
+languages:
+    - Node
+---
+```
+
+These will be rendered as tutorials in the tutorial listing pages, but when clicked the user will go to the original source of the content.

data/lib/nexmo_developer/app/views/contribute/structure/content-types/use-cases.md

@@ -0,0 +1,18 @@
+---
+title: Use Cases
+navigation_weight: 5
+---
+
+# Use Cases
+
+Use Cases provide guidance on how to implement real-world scenarios using Vonage APIs and third-party APIs and products.
+
+A Use Case is implemented as a single markdown file, but when the platform renders it, the headings appear as navigable steps on the right-hand side of the page:
+
+![Sample use case](/assets/images/contributing/uc-example.png)
+
+You have more flexibility when writing a use case than you do with a tutorial. Usually you will start by showing readers how to set up, configure and then run a demo project and then break it down to show how it works. But you might choose to adopt a more "step-by-step" approach. Ultimately, it's up to you.
+
+> **Unsure if this is the right format?** Please read our [Tutorials and Use Cases guide](/contribute/guides/tutorials-and-use-cases) to help you decide.
+
+If you are sure that a Use Case is what you need, please see our [Use Case guide](/contribute/tutorials-and-use-cases/use-cases) to learn how to create one.

data/lib/nexmo_developer/app/views/contribute/structure/overview.md

@@ -0,0 +1,55 @@
+---
+title: Overview
+---
+
+# Structure Overview
+
+This document provides a guide for how documentation is structured in Nexmo Developer.
+
+## How should I structure documents?
+
+Nexmo Developer content should be designed to be clear, concise and consistent in that order.
+
+Exceptions can be made to break consistency where it makes sense, particularly in scenarios where the content would be unnecessarily verbose or the structures outlined in this guide are unsuited to the material.
+
+![Code Snippets](/assets/images/contributing/structure.png)
+
+## Structure
+
+Nexmo Developer is structured by context and by product. The four main sections of Nexmo Developer are:
+
+1. Documentation
+2. API References
+3. SDKs and Tools
+4. Community
+
+### Documentation
+
+This section hosts the bulk of the written content for the NDP. The content is structured by products each of which have the following four sections:
+
+  * **[Overviews](/contribute/structure/content-types/overviews)** - The first pages you reach when you select a product.
+  * **[Guides](/contribute/structure/content-types/guides)** - Provide key concepts in more depth than the overview.
+  * **[Code Snippets](/contribute/structure/content-types/code-snippets)** - Used as a quick reference of how to do something specific.
+  * **[Tutorials](/contribute/structure/content-types/tutorials)** - Step-by-step guide on how to do something. There is also a detailed [guide to tutorials](/contribute/guides/tutorials) available.
+  * **[Use Cases](/contribute/structure/content-types/use-cases)** - Multi-product scenarios using Vonage APIs and those of other providers.
+
+### API Reference
+
+API Reference pages document the following properties of the API:
+
+- Description
+- Overview
+- Resource Model
+- Endpoints
+  - URL
+  - Method
+  - Parameters
+  - Response
+
+### SDKs and Tools
+
+A section that outlines our SDKs, Tools, Libraries etc. The repository README should provide all necessary information.
+
+### Community
+
+As it develops, the community section will be a repository for 'cool hacks', open source projects that use Nexmo, the events that Nexmo will attend or sponsor, and blog posts that the community has written about Nexmo.

data/lib/nexmo_developer/app/views/contribute/tutorials-and-use-cases/tutorials.md

@@ -0,0 +1,197 @@
+---
+title: Creating a Tutorial
+navigation_weight: 1
+---
+
+# Tutorials
+
+Step-by-step procedures are documented using tutorials in Nexmo Developer. This topic describes how to create a new tutorial.
+
+> **Wait!** Are you sure that a Tutorial is the right format for what you want to achieve? Please read our [Tutorials and Use Cases guide](/contribute/guides/tutorials-and-use-cases)
+
+Tutorials support multiple programming languages. You can select the language you require from the list provided.
+
+## Directory structure
+
+Tutorials have a specific directory layout for content. The whole tutorial structure is driven by a root configuration file, which is described in more detail later in this topic. If your tutorial is called `my-tutorial` you would create a file called `my-tutorial.yml`. Configuration files are located in `config/tutorials`. Content files are located in `_tutorials`.
+
+### Configuration files
+
+```
+config/tutorials/en/product/my-tutorial/my-tutorial.yml
+```
+
+Note that tutorials may be organized on a per-product basis. In the previous example `product` might be `voice-api` or `client-sdk` for example. This structure is preferable but optional.
+
+If you have steps in the tutorial that are specific to other languages these would also have driver configuration files:
+
+```
+config/
+  tutorials/
+    en/
+      product/
+        my-tutorial.yml
+        my-tutorial/
+          javascript.yml
+          python.yml
+          kotlin.yml
+```
+
+As shown there can be a generic 'driver' file to define the order of the steps, or you can have language specific driver files that define the sequence of steps for a specific language. For example, `javascript.yml` would define the steps for a JavaScript-specific version of the tutorial.
+
+### Content files
+
+The content files pointed to by the configuration files are located in a separate directory structure. The root directory is `_tutorials/en`. For the example here your content would be located in `_tutorials/en/my-tutorial`:
+
+```
+_tutorials/en/
+  step-a.md
+  step-b.md
+  product/
+    step-c.md
+    step-d.md
+    my-tutorial/
+      step-e.md
+      step-f.md
+      step-g/
+        python.md
+        kotlin.md
+      step-h/
+        javascript.md
+```
+
+You may also have steps that are specific to a programming language, such as Python. In this case you would locate language specific steps in a subfolder for that step. In the previous example:
+
+* Steps `step-a` and `step-b` are shared across all tutorials.
+* Steps `step-c` and `step-d` are shared across all tutorials of the product `product`.
+* Steps `step-e` and `step-f` are specific to `my-tutorial`.
+* Steps `step-g` contains language-specific versions of the step, although some steps may only be required for a single language.
+* Step `step-h` is only relevant for JavaScript.
+
+Remember that all steps are referenced from the configuration file in the step-order they are to be displayed in the rendered tutorial.
+
+## Tutorial config file
+
+Tutorial configuration files are located in `config/tutorials` and the name of the file is used as the name of the tutorial in the URL.
+
+For example, the configuration for `https://developer.nexmo.com/client-sdk/tutorials/in-app-messaging` is located in `config/tutorials/en/in-app-messaging/*.yml`. The contents of the JavaScript config file is shown here:
+
+```yaml
+title: Creating a web-based chat app
+description: Create a web application that enables users to message each other
+products:
+  - client-sdk
+
+introduction:
+  title: Introduction to this task
+  description: This task shows you how to create a web chat application using the JavaScript Client SDK.
+  content: |
+    # Introduction
+    In this task, you will learn how to create and configure a Client SDK Application and then code a web app that enables two users to send messages to each other.
+
+    First, you will create a Conversation and two Users. Then, you will authenticate these Users and add them to the Conversation as Members.
+
+    Finally, you will implement chat functionality in your application, including the ability to view and send messages and be notified when either party is currently typing.
+
+    The source code is available [on GitHub](https://github.com/nexmo-community/ip-messaging-tutorial).
+
+prerequisites:
+  - create-nexmo-account
+  - install-nodejs
+  - install-nexmo-cli-beta
+  - install-node-client-sdk
+  - run-ngrok
+
+tasks:
+  - client-sdk/create-application
+  - client-sdk/create-conversation
+  - client-sdk/create-users
+  - client-sdk/in-app-messaging/add-users-to-conversation
+  - client-sdk/generate-jwts
+  - client-sdk/in-app-messaging/create-ui
+  - client-sdk/in-app-messaging/authenticate-users
+  - client-sdk/in-app-messaging/join-conversation
+  - client-sdk/in-app-messaging/show-message-history
+  - client-sdk/in-app-messaging/send-message
+  - client-sdk/in-app-messaging/typing-indicators
+  - client-sdk/in-app-messaging/run-application
+
+conclusion:
+  title: What's next?
+  description: What else can you do with the Client SDK?
+  content: |
+
+    # What's next?
+    You can do a lot more with the Client SDK.
+
+    We want to hear what ideas you have in mind? Contact us at <a href="mailto:devrel@vonage.com">devrel@vonage.com</a>
+
+    See [Client SDK documentation](/client-sdk/overview).
+```
+
+You see the `prerequisites` section which is a list of files that provide Markdown content for each of the prerequisites list:
+
+![Prerequisites](/assets/images/contributing/prereqs.png)
+
+Clicking on any prerequisite displays the content.
+
+The main steps of the tutorials are defined in the `tasks` section. This is a list of subtasks, or steps, that are combined to produce a single parent tutorial.
+
+Each of these files live in the `_tutorials` folder and are written using Markdown. For example `client-sdk/create-application` is located in `_tutorials/client-sdk/create-application.md` with the following contents:
+
+```yaml
+---
+title: Create a Nexmo Application
+description: In this step you learn how to create a Nexmo Application.
+---
+
+# Create your Nexmo Application
+
+...
+```
+
+## Content reuse
+
+The idea behind having standalone step files is that you can define each task once, such as for create application, and then reference it in every tutorial that requires it.
+
+Being able to reuse content in this way leads to far greater consistency, more rapid documentation development, and ease of maintenance.
+
+## Adding more context
+
+Although you want as much content reuse as possible, each step you want a customer to perform will need some context. To provide this, you can define an `introduction` and `conclusion` in a tutorial config file (`config/tutorials/tutorial-name.yml`):
+
+```yaml
+title: Creating a web-based chat app
+description: Create a web application that enables users to message each other
+products:
+  - client-sdk
+
+introduction:
+  title: Introduction to this task
+  description: This task shows you how to create a web chat application using the JavaScript Client SDK.
+  content: |
+    # Introduction
+    In this task, you will learn how to create and configure a Client SDK Application and then code a web app that enables two users to send messages to each other.
+
+    First, you will create a Conversation and two Users. Then, you will authenticate these Users and add them to the Conversation as Members.
+
+    Finally, you will implement chat functionality in your application, including the ability to view and send messages and be notified when either party is currently typing.
+
+    The source code is available [on GitHub](https://github.com/nexmo-community/ip-messaging-tutorial).
+
+...
+
+conclusion:
+  title: What's next?
+  description: What else can you do with the Client SDK?
+  content: |
+
+    # What's next?
+    You can do a lot more with the Client SDK.
+
+    We want to hear what ideas you have in mind? Contact us at <a href="mailto:devrel@vonage.com">devrel@vonage.com</a>
+
+    See [Client SDK documentation](/client-sdk/overview).
+```
+
+This content is provided directly in the tutorial configuration file as it is specific to the current tutorial and is not intended to be reused. Remember if you have language-specifc tutorials there will be one configuration file for each supported language.

data/lib/nexmo_developer/app/views/contribute/tutorials-and-use-cases/use-cases.md

@@ -0,0 +1,22 @@
+---
+title: Creating a Use Case
+navigation_weight: 2
+---
+
+# Creating a Use Case
+
+A Use Case shows how readers how they might implement a real-world application.
+
+Use Cases are simpler to write than Tutorials, because the entire content exists in a single markdown file.
+
+> **Wait!** Are you sure that a Use Case is the right format for what you want to achieve? Please read our [Tutorials and Use Cases guide](/contribute/guides/tutorials-and-use-cases) before continuing.
+
+Create the file for your Use Case in the appropriate language folder for your locale in the `_use_cases` directory, e.g. `_use_cases/en`, for English.
+
+Begin your Use Case with a Level 1 heading (`#`) and suitable introductory paragraph.
+
+Each main topic within your Use Case should be a Level 2 heading (`##`). You can create subheadings under each of the main topics, but please try to not go beyond Level 3 (`###`) unless absolutely necessary. Please avoid anything beyond a Level 4 (`####`) heading.
+
+![Creating a Use Case](/assets/images/contributing/create-a-uc.png)
+
+You should state any prerequisties, which can be either software or technical knowledge. At the end of the Use Case, provide a suitable conclusion and links to next steps (e.g. how could the user extend this example?) and further resources (links to API references, tutorials, and so on).

data/lib/nexmo_developer/app/views/dashboard/_performance_table.html.erb

@@ -0,0 +1,18 @@
+<table>
+  <thead>
+    <td>Page</td>
+    <td>Negative</td>
+    <td>Positive</td>
+    <td>Score</td>
+  </thead>
+  <tbody>
+    <% resources.first(5).each do |resource| %>
+      <tr>
+        <td><%= link_to resource.relative_link, resource.uri %></td>
+        <td><%= resource.feedbacks.negative.count %></td>
+        <td><%= resource.feedbacks.positive.count %></td>
+        <td><%= resource.score %></td>
+      </tr>
+    <% end %>
+  </tbody>
+</table>

data/lib/nexmo_developer/app/views/dashboard/coverage.html.erb

@@ -0,0 +1,169 @@
+<style>
+.coverage {
+    border: 1px solid white;
+    background:red;
+    text-transform: capitalize;
+    text-align: center;
+}
+
+.yaml {
+    background: green;
+    color: white;
+}
+
+.file {
+    background: orange;
+}
+
+.unsupported {
+  background: grey;
+  color: white;
+}
+</style>
+
+<center>
+    <h1>Code Snippet Stats</h1>
+
+    <br>
+    <div class="box">
+        <h2>Filter</h2>
+        <%= form_tag({}, {:method => :get}) do %>
+            <div>
+                Product: <%= select_tag :product,
+                    options_for_select([['All', nil]].concat(DocumentationConstraint.product_with_parent_list), params[:product]),
+                    onchange: "this.form.submit();" %>
+                Show Only: <%= select_tag :only,
+                    options_for_select([['All', nil], 'yaml', 'file'], params[:only]),
+                    onchange: "this.form.submit();" %>
+            </div>
+        <br>
+        <p><label>Ignore Languages:</label> <input type="text" name="ignore" placeholder="curl,php" value="<%=params[:ignore]%>" /></p>
+        <p><label>Hide json/xml entries:</label> <input type="checkbox" name="hide_response" value="1" <%= params[:hide_response] ? 'checked' : '' %> /></p>
+        <br />
+        <p><label>Ignore Products:</label> <input type="text" name="ignore_products" placeholder="conversation,messages,dispatch,audit" value="<%=params[:ignore_products]%>" /></p>
+        <p><label>Show only GA products:</label> <input type="checkbox" name="show_ga_only" value="1" <%= params[:show_ga_only] ? 'checked' : '' %> /></p>
+        <br>
+    <%= link_to 'Reset', '/coverage' %> &nbsp;
+    <%= submit_tag 'Update', class: 'button' %>
+<% end %>
+    </div>
+</center>
+<br>
+
+ <h2>Executive Summary</h2>
+<div class="Vlt-table Vlt-table--bordered">
+  <table>
+    <thead>
+    <tr>
+      <th>Language</th>
+      <th>Available</th>
+      <th>Percentage</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% @overall_summary['langs'].each do |lang, value| %>
+      <tr>
+        <td><%= lang %></td>
+        <td><%= value %>/<%= @overall_summary['blocks'] %></td>
+        <td><%= (value/@overall_summary['blocks'].to_f*100).round(2) %>%</td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+</div>
+
+<hr style="clear:both;" />
+
+<div class="box">
+    <h3>Code Snippet Rating Scale</h3>
+<div style="text-align: center; padding: 5px; background: red; width: 33%; float: left; color: white;">Missing block (worst)</div>
+<div style="text-align: center; padding: 5px; background: orange; width: 33%; float: left;">File based block</div>
+<div style="text-align: center; padding: 5px; background: green; width: 33%; color: white; float:left; margin-bottom: 8px;">Yaml based block (best)</div>
+
+<ul>
+    <li>YAML Code Snippets in <code>_examples</code> is our preferred way to handle blocks in Nexmo Developer. It's a good balance of consistency and flexibility.</li>
+    <li>Before defining blocks as individual config files, they were all defined together in <code>config/code_examples.yml</code> and each quick start would be a markdown file that referenced <code>config: product.block_name.language</code>. This is the same as the current system, but with one additional layer of redirection</li>
+    <li>Prior to keeping Code Snippets in the code snippet repos, we committed the files directly to NDP in <code>_examples</code>. This has been deprecated for a long time and should be cleaned up as it prevents code reuse</li>
+</ul>
+</div>
+
+<hr style="clear:both;" />
+
+<% @complete_coverage.each do |toplevel, blocks| %>
+    <% next if @product and not toplevel == @product  %>
+    <h2><%= toplevel %></h2>
+    <% # Per-section statistics per language%>
+
+  <%
+    section = @toplevel_summary[toplevel]
+  %>
+  <h3>Section Summary</h3>
+
+  <div class="Vlt-table Vlt-table--data Vlt-table--bordered">
+  <table>
+    <thead>
+    <tr>
+      <th>Language</th>
+      <th>Available</th>
+      <th>Percentage</th>
+    </tr>
+    </thead>
+    <tbody>
+    <% section['langs'].each do |lang, value| %>
+      <tr>
+        <td><%= lang %></td>
+        <td><%= value %>/<%= section['blocks'] %></td>
+        <td><%= (value/section['blocks'].to_f*100).round(2) %>%</td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+  </div>
+
+  <% # In-depth statistics about each block %>
+    <% blocks.each do |section, entries| %>
+        <h3><%= section %></h3>
+    <div class="Vlt-table Vlt-table--data Vlt-table--bordered">
+        <table>
+            <thead>
+                <tr>
+                <td>Block</td>
+                <% @supported_languages.each do |lang| %>
+                    <td><%= lang %></td>
+                <% end %>
+                </tr>
+            </thead>
+            <tbody>
+                    <%
+                      coverage = {}
+                      count = 0
+                    %>
+                <% entries.each do |name, languages| %>
+                    <% count += 1 %>
+                    <tr class="Vlt-table__row--nohighlight">
+                        <td style="width: 200px;"><strong><%= name %></strong></td>
+                        <% @supported_languages.each do |lang| %>
+                            <%
+                                coverage[lang] = 0 unless coverage[lang]
+                                coverage[lang] += 1 if languages[lang]
+
+                                l = languages[lang]
+                                t = l['type'] if l
+                                location = l['source_path'] if l
+                            %>
+                        <td title="<%= location %>" class="coverage <%= t %>"><%= t %></td>
+                        <% end %>
+                    </tr>
+                <% end %>
+                <tr class="Vlt-table__row--nohighlight">
+                    <td><strong>Coverage</strong></td>
+                    <% @supported_languages.each do |lang| %>
+                        <td><%= coverage[lang]%>/<%= count %> (<%= (coverage[lang]/count.to_f*100).round(2) %>%)</td>
+                    <% end %>
+                </tr>
+            </tbody>
+        </table>
+    </div>
+    <% end %>
+    <hr>
+<% end %>