Documentation SDK

Overview

YaaS uses the Documentation SDK to publish documentation in the Dev Portal and the Knowledge Hub. Use the SDK to document your API.

The Documentation SDK is a tool that allows you to create and deliver documentation content and release notes, without being dependent on a YaaS API. The documentation source files are stored directly in your application source code repository so you can work on documents and code in parallel, using the same tools and flows. The content development process is a part of the continuous delivery cycle of your software. Release your documentation, application, and release notes at the same time.

The Documentation SDK provides all the necessary technical guidelines for how to write and publish documentation. Follow the defined set of rules to structure your documents accordingly, and to find out how to store them. Try the different possibilities for content display presented in the Syntax section, and see your content in a preview using the Online Editors. Finally, learn how to successfully publish your documents.

Technical scope

The Documentation SDK allows you to generate your product documentation. In the Documentation SDK, "generating" your documentation means compiling one or more static web pages that you can host anywhere you want. You can use this SDK locally on your machine when writing your product content. You can also use it on a server, automated through continuous integration tools such as Travis CI or Jenkins. One of the elements of the open source Documentation SDK is the Dev Portal, where you can build your documents. Your use cases can differ depending on your organization's structure and development cycles. The SDK is flexible enough so that you can decide, on your own, how you use it and how you automate it.

The SDK makes it possible to distribute the content in different locations. This approach is called distributed source publishing. Imagine your product consists of 40 different documentation topics. You can document them all in one portal, but store content sources in 40 different repositories, managed by different teams using Git.

Content Storage

The solution for writing documentation in YaaS is based on Git. Git is a Version Control System (VCS) that records changes to files over time, and you can revert to a particular version as needed. Thanks to Git's data flow, many people can work on the same project without interrupting each other.

Store all files you create in a project in a Git repository, where you can also create different branches to work on ideas and changes to your project. When you are ready, merge one of these branches to your main production branch, usually called master, which holds the final version of your documentation.

These are two Git hosting providers: GitHub and Bitbucket.

To quickly learn more about Git, see these websites:

• https://try.github.io
• https://guides.github.com
• https://www.codecademy.com/learn/learn-git

Examine the Document Structure

Product documentation consists of a set of documents. Each document, including release notes, consists of two parts: Metadata and Content. The following example illustrates the required structure:

---
metadata: value or text string
another_metadata: value or text string
---

The content of your file.

The next metadata example shows a document titled "Metadata and Content", which appears in the "Structure" section in the left-side navigation:

---
title: Metadata and Content
type: Structure
---

This is an example of file content written in <strong>HTML</strong> and **Markdown**.

Metadata

Metadata is required for documents to display properly in the Dev Portal or the Knowledge Hub. The metadata varies depending on the document type. It is important to use the exact format. See the Metadata section to find templates for each document type. Incorrect values can cause the document to display improperly, not to have the correct navigation, or sometimes not to display at all.

For instance, you can use the following metadata:

1. title: This defines the title of the document.
2. type: This metadata groups documentation together, mainly for the purposes of left-side navigation. Multiple documents that use the same type generate a grouping. For example, if you have multiple tutorials, you can group them below a navigation node called Tutorials. You can see an example of this grouping in the Document service.

The only exception to the rule that requires metadata is when your document contains content that is reused in multiple documents. See the Reuse Content section for more details and to learn about partials.

Content

The content is the part of the file that includes the body of your document, and displays on the website after publishing. The content is usually written in HTML syntax. There is also a plug-in that enables composition in Markdown (MD), and even a mix of HTML and MD. The composition choice is a personal preference, but being a simplified markup language, MD has some limitations. For example, you can only use HTML in panels.

You can learn about HTML and MD syntax from the following sources:

• HTML: http://www.w3schools.com/html/default.asp
• Markdown: http://daringfireball.net/projects/markdown/syntax

Use the customized Content Editor to see how your MD and HTML display in the Dev Portal.

Location of Documents in a Repository

This section describes the folder structure of the documentation repository and how to store and name files within the repository. Use the Git solution and follow all the rules for document structure to write the necessary documentation for your product, including release notes. Next, create the folder structure, as described in this topic, in your repository to store all the files. Then, place your documents in the locations indicated.

In a repository, the docu directory is the root directory for documentation. The docu directory contains the following folder structure, depending on the Dev Portal section:

Topic order

About

You learned how to create, structure, and store documents in the Basics section. In this section, learn how to write and edit the content itself. Write your documents in Markdown, HTML, or a mixture of those two. Use the guidelines in this Syntax section to compose and format your text. Choose from different tools and techniques to author documentation, and also select formatting options for the content. For example, there is more than one way to compose bullet points or tables, and there are also pre-formatted panels you can include in your documentation. Make your content more eye-catching and insert diagrams, images, or videos. It is you who decides how to present the information you want to convey. However, it is important for the content to be readable and user-friendly.

Basic Formatting

The following examples illustrate the basic text styles:

Bullets and Numbers

HTML and Markdown languages allow you to use unordered, or bulleted lists, and ordered, or numbered lists. You can even mix the two together.

Ordered lists

<ol>
<li>Han Solo</li>
<li>Darth Vader</li>
<li>Boba Fett</li>
<li>Chewbacca</li>
<li>Master Yoda</li>
<li>Princess Leia</li>
</ol>

1. Han Solo
2. Darth Vader
3. Boba Fett
5. Chewbacca
8. Master Yoda
1. Princess Leia

Unordered lists

<ul>
<li>Han Solo</li>
<li>Darth Vader</li>
<li>Boba Fett</li>
<li>Chewbacca</li>
<li>Master Yoda</li>
<li>Princess Leia</li>
</ul>

-  Han Solo
-  Darth Vader
+  Boba Fett
+  Chewbacca
-  Master Yoda
+  Princess Leia

Mixing ordered and unordered lists

<ol>
<li>Jedi</li>
    <ul>
    <li>Master Yoda</li>
    <li>Luke Skywalker</li>
    <li>Obi-Wan Kenobi</li>
    </ul>
<li>Sith</li>
    <ul>
    <li>Darth Vader</li>
    <li>Emperor Palpatine</li>
    </ul>
<li>Mercenaries</li>
    <ul>
    <li>Rebel</li>
        <ul>
        <li>Han Solo</li>
        <li>Chewbacca</li>
        </ul>
    <li>Empire</li>
        <ul>
        <li>Boba Fett</li>
        </ul>
    </ul>
</ol>

1.  Jedi
    - Master Yoda
    - Luke Skywalker
    - Obi-Wan Kenobi
2.  Sith
    - Darth Vader
    - Emperor Palpatine
3.  Mercenaries
    - Rebel
        + Han Solo
        + Chewbacca
    - Empire
        + Boba Fett

Code Snippets

To add a code snippet to the document, put it in a block between three back tick characters (```) with information about the highlight type.

Code example with a JSON object

This is an example of a code snippet highlighting a JSON object:

Code

``` json
{
 "kind": "History",
 "name": "Thorgal"
}
```

Result

{
"kind": "History",
"name": "Thorgal"
}

Code example without highlighting

If you don't want to use highlighting, then insert no-highlight code as shown in this example:

Code

``` no-highlight
{
 "kind": "History",
 "name": "Thorgal"
}
```

Result

{
"kind": "History",
"name": "Thorgal"
}

Columns

To use two columns in the midsection of a document, use HTML code. For example, to have a code snippet in one column, and a note panel in the other column, choose the width of each section by changing the width: value. Remember that the summed value can not be higher than 100%.

Example

<section style="width: 50%; float:left;">
    <div>Column 1 text here... Column 1 text here... Column 1 text here... Column 1 text here...</div>
</section>
<section style="width: 50%; float:left;" >
    <div>Column 2 text here... Column 2 text here... Column 2 text here... Column 2 text here...</div>
</section>

Result

Diagrams

You can render diagrams in the Dev Portal using one of these methods:

• Wrap them in code block ``` markdown. Include the .md extension in your file name.
• Wrap them in a div tag with the class mermaid.

```
your diagram code
```

or

<div class="mermaid">
your diagram code
</div>

Example diagrams:

Yoda service flow

Diagram:

Source code:

```
graph LR
  subgraph Yoda Service Components
  yoda --> document
  document --> yoda
    subgraph YaaS Services
    oauth
    marketplace
    product
    account
    end
  end
  yoda -- R> --> oauth
```

Getting started with YaaS

Diagram:

Source code:

```
graph LR
  USER --> a1(Prerequisites)
  a1 -->|New to YaaS?| b1(First Steps With APIs)
  a1 -->|Accustomed to Yaas?| c1(Start Developing)
  b1 --> c1
  c1 --> d1(Set Up The Environment)
  d1 -->|Create a Service?|e1(Create a Service)
  d1 -->|Or?|f1(Download the Wishlist Example)
```

Escape Markdown

In Markdown, you can generate literal characters which would otherwise have special meaning in Markdown’s formatting syntax. To escape the Markdown language, use the backslash (\). For example:

Expand and Collapse

You can use the expand and collapse feature as shown in the following example.

Headings and Sections

HTML and Markdown languages allow you to render headings and create sections.

<h3>Header 3</h3>
<h4>Header 4</h4>
<h5>Header 5</h5>
<h6>Header 6</h6>

### Header 3
#### Header 4
##### Header 5
###### Header 6

Hide Content from Normal View

To prevent content from rendering, or to leave a comment for an editor, use the HTML comment tag: <!--...-->. The Dev Portal removes all comments in the generated content, so any internal comments are not available to the Dev Portal readers.

Code:

<!-- This line won't be rendered! -->
Yay! It works!
<!-- But it's still there... -->

Result:

Yay! It works!

Images and Attachments

Put images and downloadable files in the following directories:

• For documents:
• Images: docu/files/img
• Attachments: docu/files/download
• For release notes:
• Images: docu/release_notes/img
• Attachments: docu/release_notes/download

The following are code examples for images and attachments:

Code

Result

1. 

2. 

3. ZIP file containing a Hybris banner.

4. 

Linking

Use either HTML or MD to point readers to another resource for information.

Cross-linking in the same portal

You can either link topics in the same document or cross-link topics in two different documents. A topic is a unit of content within a document.

https://devportal.yaas.io/services/checkout/latest/#Tutorial

Linking to external pages

Markdown inside DIV Elements

Although Markdown (MD) is a great shortcut, it has one big limitation. MD code does not render inside of HTML blocks, such as <div></div>. Basic formatting as described in the Basic Formatting section works, but MD code in bullets and numbers, or code snippets doesn't work.

There are two solutions:

• Use pure HTML such as:
  • <ul><li>for list items</li></ul>
  • <pre class="highlight"><code>for code blocks</code><pre>
• The Dev Portal uses a plug-in designed to overcome this limitation. Thanks to the plug-in, you can render MD code by removing the .md extension from your file, and using the <t render="html.md"> tag where you want to render MD.

The following example shows how to render a code snippet highlighting a JSON object inside HTML blocks using the <t render="html.md"> tag. The code snippet is in MD and the blocks are an expand and collapse div element:

Code

<div class="expand-collapse" data-caption="Expand for More Details">
<t render="html.md">
``` json
{
  "test":"some",
  "test":"plus"
}
```</t>
</div>

Result

{
  "test":"some",
  "test":"plus"
}

See also a more complex example:

Code

<t render="html.md">
It is an **example** of the `div` issue:
* It looks complex

* But it covers the most probable usage scenario
</t>
<p>Here's an example of the `t` tag within a `div` tag:</p>
<div class="expand-collapse" data-caption="Expand for More Details">
<t render="html.md">
``` json
{
  "test":"some",
  "test":"plus"
}
```
</t>
</div>

Result

It is an example of the div issue:

{
"test":"some",
"test":"plus"
}

Panels

Panels are colorful containers that call out important or additional information within a topic. The following table outlines the guidelines and recommended use for each panel type.

Reuse Content

A developer wants to reuse code whenever possible, and a writer wants to reuse content where applicable. To enable this functionality, the Dev Portal uses a plug-in called Partials. Therefore, content that you want to reuse is called a partial.

Follow these steps to create and reference partials.

1. Create a text file in the docu/partials directory of your project. If the directory doesn't exist, create it.

   • Prefix the file name with the name of your service, in all lowercase letters and no spaces, followed by an underscore and the partial name. For example, yourservice_partial_name.

2. Include the content you want to reuse in the text file.

3. In your documentation file, add the following code where you want to pull in the content from the partial file you created. Replace yourservice_partial_name with the name of your partial:

<%- @partial('yourservice_partial_name') %>

For example, to show reusable Cart Calculation prerequisite content in your document, replace yourservice_partial_name in the preceding code with the partial name cartcalculation_prerequisites.

1. Name the documentation file that references the partial so that it ends with the .eco extension. For example, rename a file called IntroductiontoTutorials.html.md to IntroductiontoTutorials.html.md.eco.

Tables

You can use standard HTML formatting or Markdown (MD) to create tables. Tables are not part of MD itself, but GitHub Flavored Markdown (GFM) adds the table functionality.

HTML tables

Create a table in HTML as shown in the following example:

Code

<table>
<tr>
  <th>One</th>
  <th>Two</th>
  <th>Three</th>
</tr>
<tr>
  <td>One is the loneliest number that you'll ever do.</td>
  <td>Two can be as bad as one. It's the loneliest number since the number one.</td>
  <td>Three blind mice, see how they run.
</tr>
<tr>
  <td>The rows have different background colors for easier readability.</td>
  <td>They alternate from here if you include more rows.</td>
  <td>Like a checkbook registry.</td>
</tr>
</table>

Result

Markdown tables

Create an MD table by separating columns with a pipe |, and separating the header row for each column using hyphens -, as shown:

Code

|Header 1|Header 2|Header 3|Header 4|Header 5|
|--------|--------|--------|--------|--------|
|Content |looks   |nicer   |in      |tables  |
|Does    |it      |not     |?       |?       |
|        |        |        |        |        |

Result

The preceding MD table displays cleanly, both in a code preview and when rendered. You don't have to be as careful when making tables in MD. For example:

Code

 Header 1 |Header 2 |Header 3 |Header 4|Header 5
 ----------|----------|----------|----------|----------
 This|table |is |a |bit
 messy |but |it |will|render
 nicely|too|!!||

Result

Before You Start

From the preceding sections, you understand how to use metadata and how to structure and format your content. You also learned that all documents are stored in a repository. In this section, learn how to build a documentation portal.

To use the SDK locally, start using a YaaS open source project called docpad-skleton-apidocs as your base, and then set up your work with Docker. You don't need to perform any complex installations that generate cross-platform issues and dependencies. Docker simulates the same behavior you expect on the server, locally. The configuration you set up on your local system within Docker works the same on any other operating system.

Prerequisites

Before building your documentation portal, complete these requirements:

• Get a GitHub account or any other Git hosting service account.
• Install Docker.

Build Your Documentation Portal Locally

The steps that follow describe how to build a documentation portal locally.

Start a documentation portal container

After you get a Git account and install Docker, follow these instructions to start a documentation portal container.

1. Open a terminal window.
2. Run the command:

   docker run -it --name api-doc-sample -p 9778:9778 derberg/dsa-quickstart
   npm run start
   

3. In your browser, access the documentation portal through this link: http://localhost:9778/.
4. To end your work with the documentation portal container, in the terminal application, press CTRL+c on your keyboard to close the server.
5. Type exit and press Enter to leave the container.

Copy samples and configure the template

In this step, copy the available samples, modify them, and adjust the template to your content. You can perform the actions either with Git or directly in the GitHub UI.

1. Go to your GitHub or other Git account and fork the chewie-sample-data repository. In GitHub, click Fork in the top-right corner of the page.
2. To make sure that your setup is correct and to see your content in the portal, make some changes in the forked repo in the /content/services/hodoripsum/docu/files/overview.html.md.eco file.
3. Modify the registry by editing the /registry/hodoripsum.json file and changing location url to your fork URL: https://github.com/{your_github_username}/chewie-sample-data.
4. Run the template again, using a different registry path and a separate initialization:

   export REGISTRY_PATH=https://github.com/{your_github_username}/chewie-sample-data
   npm run init
   npm run start
   

5. Use the preceding steps to modify the template and fill it with your content. Examine the forked sample repository to see how the content is structured, and how the registry works. For further details see the JSON Schema section.

JSON Schema

In this section, you learn what a sample .json entry looks like and what a JSON schema is.

Examine the following .json sample file and adjust the template to your use case.

{
  "name": "Samuel L Ipsum",
  "type": "services",
  "area": "Movies",
  "source": [
    {
      "version": "v2",
      "latest": true,
      "location": "https://github.com/YaaS/chewie-sample-data.git",
      "docu_dir": "/content/services/samuellipsum",
      "baseUri": "http://slipsum.com",
      "branch_or_tag": "master",
      "raml": "/content/services/samuellipsum/src/main/resources/api/samuel-ipsum.raml"
    },
    {
      "version": "v1",
      "latest": false,
      "location": "https://github.com/YaaS/chewie-sample-data.git",
      "docu_dir": "/content/services/samuellipsum",
      "baseUri": "http://slipsum.com",
      "branch_or_tag": "master",
      "raml": "/content/services/samuellipsum/src/main/resources/api/samuel-ipsum.raml"
    }
  ]
}

JSON schema describes the data structure of a .json file. It helps validate the format of your registry JSON.

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "properties": {
        "name": {
            "type": "string",
            "description": "The name of the topic"
        },
       "type": {
           "type": "string",
           "enum": ["services"],
           "description": "The Dev Portal section. Services means the content should display in the API Docs section."
        },
        "area": {
            "type": "string",
            "description": "The name of the more general area the service belongs to."
        },
        "source": {
            "items": {
                "properties": {
                    "version": {
                       "type": "string",
                       "description": "The number of the version. Use only lowercase alphanumeric characters and hyphens. Start with a lowercase letter, and end with a lowercase alphanumeric character."
                    },
                    "latest": {
                        "type": "boolean",
                        "description": "Information if the version is the latest one. The value is set to false by default."
                    },
                    "location": {
                        "type": "string",
                        "description": "The shh link to the service repository."
                    },
                    "docu_dir": {
                       "type": "string",
                       "description": "The source path to the documentation directory, if different then the root of the repository."
                    },
                    "baseUri": {
                        "type": "string",
                        "description": "The baseUri path which is built from builder_org, builder_identifier, and version properties. There is no need to provide baseUri if you provide builder_org, builder_identifier and version properties."
                    },
                    "branch_or_tag": {
                        "type": "string",
                        "description": "The name of the branch or tag in the repository that contains documentation."
                    },
                    "raml": {
                        "type": "string",
                        "description": "The source path to the raml file. Provide the path only if there is more than one raml file. If only one raml file exists, the system matches it by default."
                    }
                },
                "type": "object",
                "required": ["location", "branch_or_tag"]
            },
            "type": "array",
            "description": "The content sources location and more specific version details."
        }
    },
    "type": "object",
    "required": ["name", "type", "area", "source"]
}

See the following table with the description of the JSON schema for Services in the Dev Portal.

Look and Feel Customization

By default, your documentation portal displays with a sample landing page. Creating a custom directory with customization files enables modifications in the look and feel of your documentation portal. This section teaches you how to create files that enable modifying the navigation and the landing page.

Once you have all your customization files ready and located in a local directory, you can mount the directory and run your customized documentation portal. See the following guidelines:

1. Create a new directory and name it my-customization.
2. In the my-customization directory place all your customization files.
3. Mount the my-customization directory by running the following command:

   docker run -it --name api-doc-sample -p 9778:9778 -v {{PATH_TO_CUSTOMIZATION_DIR}}:/docpad-skeleton-apidocs/customization derberg/dsa-quickstart
   

   For example:

   docker run -it --name api-doc-sample -p 9778:9778 -v ~/Desktop/my-customization:/docpad-skeleton-apidocs/customization derberg/dsa-quickstart
   

4. Run the following command:

   npm run start
   

5. In your browser, access the documentation portal through this link: http://localhost:9778/.

Navigation

To customize the navigation of your documentation, in the my-customization directory create a JSON file and name it config.json. Compose the config.json file according to the JSON schema provided and as shown in the following example:

  {
      "$schema": "http://json-schema.org/draft-04/schema#",
      "properties": {
          "generalNav": {
              "items": {
                  "properties": {
                      "href": {
                          "description": "The link to the resource.",
                          "type": "string"
                      },
                      "name": {
                          "description": "The name of the resource.",
                          "type": "string"
                      },
                      "id": {
                          "description": "The ID of an HTML element.",
                          "type": "string"
                      }
                  },
                  "required": [
                      "href",
                      "name"
                  ],
                  "type": "object"
              },
              "type": "array"
          }
      },
      "type": "object"
  }
  

  {
    "generalNav": [
      {
        "href": "/",
        "name": "Home"
      },
      {
        "href": "/services/",
        "name": "API Docs"
      }
    ]
  }
  

Landing page

You can also customize the landing page of your documentation portal. In the my-customization directory, create an index.html file. Modify the file depending on your preferences and use case. See the following example:

<div class="landing-page-wrapper">

  <div class="jumbotron jumbotron--featured text-center">

    <div class="row u-position-relative">

      <div class="col-md-8 col-md-offset-2">
        <h1 class="jumbotron__title jumbotron__title--featured">My Documentation Portal</h1>
      </div>

    </div>

  </div>

</div>

Publish Your Documentation Portal

After you build your documentation locally, you can publish the content. To show your documentation portal to the public, use GitHub Pages. Use the following steps to publish your content.

1. Configure Git inside the container:

   git config --global user.email "you@example.com"
   git config --global user.name "Your Name"
   

2. In your GitHub account, create a new repository with the name {your_github_username}.github.io. Set the repository to public and initialize it with a readme file.

3. Provide the necessary variables using the following commands:

   export docuURL=https://{your_github_username}.github.io
   export RESULT_LOC=https://github.com/{your_github_username}/{your_github_username}.github.io
   npm run init
   NODE_ENV=prod npm run compile
   npm run preparePushResult
   npm run pushResult
   

   Provide your GitHub username and password when requested.

   The initial build on GitHub Pages can take a few minutes.

4. In your browser, go to {your_github_username}.github.io to see your publicly-available documentation portal.

Update the SDK

The Documentation SDK and the Dev Portal skeleton are under constant improvement. Update your local installation of the Documentation SDK whenever a new version of the Dev Portal skeleton is available. To update the SDK, use the following commands in a terminal window:

docker pull derberg/dsa-quickstart
docker rm -f api-doc-sample
docker run -it --name api-doc-sample -p 9778:9778 derberg/dsa-quickstart /bin/bash

Metadata

Each document needs metadata, which is used to generate the documentation. To use the correct metadata type for your documents, locate the guidelines in the Metadata section for each section or document type you publish. Some metadata values are constant, others you can set yourself. Read the comments in each section for additional details.

See the Examine the Document Structure section to learn more about how to structure your documents.

The Dev Portal metadata

This table describes the metadata types and metadata values required to publish each type of document in the Dev Portal.

Content Editor

Enter content in MD or HTML syntax here and see how it renders in the Dev Portal:

Diagrams Editor