ONDEWO SDK and API Documentation

This repository was created as a solution for easier navigation of the ONDEWO SDK and API Documentations of different versions on GitHub Pages. It also allows for automated updating of the GitHub Pages Index Page through the Automated Release Process of ONDEWOs APIs.

Table of Contents

1. Setup for Development
2. Website structure
3. Data
4. Design
5. Workflow for Changes

---

Setup for Development

The repository contains all files needed to deploy it on the Index Page of the GitHub Pages Website. For Development only 2 libraries are needed:

• sass - The library containing the compiler for .scss and .sass files
• http-server - A fast and easy way to run a local server to test changes and behavior

It is recommended to install the sass library globally, since it's rather small and might be useful elsewhere

npm install -g sass

Since the http-server is only used to observe the current changes, it does not need to be installed permanently, instead it's run with the npx command in the root of the repository.

npx http-server ./

HTML files cannot understand .scss and .sass files, which is why they need to be compiled into normal .css files. To make development easier, the command can be run with the --watch flag, which will automatically compile the index.scss into index.css, as soon as changes have been saved in the index.scss file.

sass --watch style/index.scss style/index.css

---

Website structure

To make the Website as scalable as possible, both in terms of APIs and SDKs, as well as their version histories, it is dynamically generated by the index.js script. It contains a template for an API-Container, which looks like this:

<div class="d-flex bg-primary text-white border border-primary flex-row justify-content-center rounded flex-nowrap p-1  m-3">
    <div class="d-flex p-1 bg-white rounded flex-column w-50">
        <alert style="cursor: pointer;" onclick="openLink('${tech.product_link}')" class="alert bg-secondary text-light w-75 font-weight-bold">ONDEWO ${tech.name}</alert>
        <p class="text-primary">Clients SDKs on Github for</p>
        <div class="d-flex flex-row flex-nowrap">
            <img
                class="tech-logo rounded-circle border border-primary p-2"
                onclick="openLink('${tech.clients.python}')"
                src="${ondewo.ondewo.logos.python_logo}"
                alt="Python Logo"
            />
            <img class="tech-logo rounded-circle border border-primary" onclick="openLink('${tech.clients.angular}')" src="${ondewo.ondewo.logos.angular_logo}" alt="Angular Logo" />
            <img class="tech-logo rounded-circle border border-primary" onclick="openLink('${tech.clients.nodejs}')" src="${ondewo.ondewo.logos.nodejs_logo}" alt="Nodejs Logo" />
            <img class="tech-logo rounded-circle border border-primary" onclick="openLink('${tech.clients.typescript}')" src="${ondewo.ondewo.logos.typescript_logo}" alt="Typescript Logo" />
            <img class="tech-logo rounded-circle border border-primary" onclick="openLink('${tech.clients.js}')" src="${ondewo.ondewo.logos.js_logo}" alt="Javascript Logo" />
        </div>
    </div>
    <div class="d-flex flex-column w-50 m-1 ml-3">
        <p class="font-weight-bold">Version Documentation</p>
        <div id="${tech.name}-versions" class="d-flex flex-wrap w-100 bg-red">
        </div>
    </div>
</div>

Changes to this template directly affect the content and design of every API-container specified. The containers are added to the div in the index.html with id="main-container" by running a simple for-loop over the specified apis-list. The buttons that are used for the API-Versions are created dynamically as well, with the following template:

<button onclick="openVersionLink('${version.link}')" class="btn btn-secondary m-1 p-1">${version.number}</button>

---

Data

The data.js file exports an ondewo.technology list, which contains objects that represent 1 API. It also contains an ondewo.logos object, with links to all the SDK logos, for easy replacement. The documentation of every new version of an API gets added automatically by the A.R.P command of the API. The structure of the API-objects looks like this:

{
    name: 'API NAME',
    product_link: 'LINK TO THE PRODUCT ON ondewo.com',
    clients: {
        python: 'LINK TO PYTHON-GITHUB-REPO',
        ...
    },
    versions: [
        { number: 'VERSION NUMBER', link: 'LINK TO THE index.html OF THE AUTO-GENERATED DOCUMENTATION
        (e.g. ondewo-nlu-api/3.0.0/)'
        },
        ...
    ],
    end: ''
},

⚠️ Changing the structure of this object will cause problems with the Automatic Release Process of the APIs

⚠️ Clients are not dynamically generated. They need to be manually adjusted in the template of theindex.js

The end property has no meaning for the website, or the content itself. It serves as a clear boundary between the API-objects, in order for the command of the Automated Release Process to stay as simple as possible. It uses a sed command to find the correct object and their line numbers in the data.js, which needs 2 patterns, a start and end.

---

Design

The website uses the Bootstrap 4 scss library. In order to change the primary and secondary colors into the colors of the ONDEWO logo, bootstrap.scss is not directly imported into index.html, instead going through the index.scss first. This library is far more powerful than the website currently needs, but for future development all of it is still part of the repository.

---

Workflow for Changes

Any changes to this repository should be done in a new branch containing the ticket-number associated with the task.

git checkout -b ONDxxx-Name-of-the-branch

After development, a Pull Request needs to be created for the branch. The contents of the PR need to be merged into the main branch.

Before someone reviews the changes, they should be properly tested depending on their nature. These can be done manually, since this repository is small in scale and complexity and not worth a testing framework. Main problems to focus on are Responsiveness, Typos and Missing content, due to script failure.