Get started

The Developer Portal Documentation Service enables developers to write and publish project documentation with markdown files or OpenAPI/Swagger specifications. The documentation is then automatically synced and published to the documentation portal.

Prerequisites

The developer portal documentation service syncs up your documentation repository containing Markdown or OpenAPI(Swagger) files and hosts them as documentation pages.

You will need:

A TechPass account to log in and host your documentation.
A SHIP-HATS GitLab account to host your documentation’s git repository.
*To be onboarded as a publisher on the Documentation Service.

*To onboard as a publisher, please reach out to the Developer Portal Team via this form.

You can publish 2 types of documentation:

Markdown. This requires you to commit a directory of documentation markdown files to a GitHub/GitLab repository with a _sidebar.md file to format the side navigation for documentation readers.
OpenAPI/Swagger. This requires you to commit a swagger file to a GitHub/GitLab repository.

You can then publish your documentation on the Documentation Service via our publisher app (see detailed steps below).

Overview of steps

Clone the content starter kit from GitLab.
Write and preview your documentation on your machine with tools such as Docsify for Markdown, and ReDoc for OpenAPI
Create a GitHub/GitLab repository and push your documentation to it
Log in to the documentation service with your TechPass account
Go through the guided publishing flow via the publisher app.

Quickstart

The two types of documentation that you can publish are:

Markdown
Open API Specification / Swagger

The following examples show you how to get started with the creation of such docs, and also how to serve them on your local machines so that you can have a preview of how they would look like when published.

Create and Preview Markdown

You can write your documentation as a series of markdown files stored on github.com or sgts.gitlab-dedicated.com, which would be rendered by the documentation portal as documentation pages.

The easiest way to get started with writing documentation is to use a tool called Docsify, which can help you visualize the documentation pages you are writing in markdown.

You will need to have Node.js and NPM installed on your machine. Use the official installer or the nvm tool.

Create a Git repository to hold your documentation.

mkdir my-docs
cd my-docs
git init

Use the Docsify CLI to generate a documentation site. This creates an index.html file along with a few markdown text files in your directory. You can get a index.html from our innersource repo to get the same look and feel.
```
# Initialize the documentation folder with index.html and some .md files
npx docsify-cli init .
```
Start up a live-reloading server for your documentation. Open a browser and view it at http://localhost:3000.
```
# View your documentation at http://localhost:3000
docsify serve .
```

Commit your markdown files

git add --all
git commit -m "Initial commit"

From the official OpenAPI specification site:

The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection.
An OpenAPI document (or set of documents) defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.

You can define an OpenAPI or Swagger document in yaml or json and publish that on the developer documentation portal. It would be rendered as a human-readable page using the ReDoc engine.

Preview OpenAPI

You can use the redoc CLI to preview how your API documentation would look like. You will need to have Node.js and NPM installed on your machine. Use the official installer or the nvm tool.

npm i -g redoc-cli
redoc-cli serve swagger.yml

You can then navigate to http://localhost:8080 to preview your rendered API documentation:

openapi documentation with redoc screenshot

2. Push to SHIP-HATS GitLab Repo

After your Markdown or OpenAPI documentation is prepared, push it to GitLab.

Create a new sgts.gitlab-dedicated.com repository (this can be either public or private) and follow the instructions on GitLab to push your new repository to that project.

# Either SSH authentication
git remote add origin git@sgts.gitlab-dedicated.com/group/my-project.git
# Or HTTP
git remote add origin https://sgts.gitlab-dedicated.com/group/my-project.git

# Push to the master branch of your GitHub project
git push -u origin master

For Markdown Docs, your home page defaults to your README.md file at the root of your project.
For OpenAPI/Swagger Docs, you should use a YAML (.yml or .yaml extension) or JSON (.json extension) file.

3. Log in and access your Product space

Navigate to Team Docs to find the products what you can publish documentation for.

Select the Product of which you are intending to publish documentation for, then click on the “Publish documentation” button.

4. Publish your documentation with the guided Publishing Wizard

The publishing wizard will guide you through the steps required to get your documentation published.

Step 1. Select SHIP-HATS GitLab as Git Provider

Select Repo

In this step, you select a git provider (only GitHub & GitLab available for now, but more options are coming soon!) and authorise your account to the documentation service with the necessary permissions to perform publishing.

If this is your first time publishing a document, and you have not authorised your GitLab account to us before, you will be prompted to do so when you click next.

Step 2. Select a Repository

In this step, you select a repository from your GitLab account to link up to your to-be published documentation. Your personal repositories along with the repositories of any organisation/teams of which your GitLab account is an admin of, will be available for selection. You can toggle these options under the ‘Groups’ dropdown selection.

Step 3. Enter Document Details

In this step, you provide details regarding how you want your documentation to be displayed both for readers and search engines. The common options are:

Display Name: The title that people see when clicking on links to your documentation, e.g. “MyTechProduct User Guide”. The display name for your documentation must be unique across the entire site, so you would not be able to publish a documentation with the same display name as an existing one.
Description: A short description of your product, e.g. “Find out how to integrate your backend with MyTechProduct here”.
Visibility: Public (public internet) vs private (only viewable by logged in TechPass users, with further email/domain-based restrictions available).
Documentation type: choose the format of your documentation. You have two choices:
- Markdown: for general documentation consisting of text and images, such as the documentation you are reading right now.
- Swagger (OpenAPI specs): for API documentation, stored in the OpenAPI specification format in a YAML or JSON file.
Branch: Choose the branch of your GitHub/GitLab repo to publish your documentation from.

Documentation URL
Your documentation will be available at a URL determined by its given display name. For example, if your display name is “MyService User Guide”, it will be available a the URL /docs/myservice-user-guide as shown below.

For more detailed descriptions of each option, see publishing settings.

Step 4. Summary

This is the final step where you review your repository selection and inputs. Upon verifying that all configurations are in order, click on ‘Publish Documentation’ to have your documentation published!

Once published, your documentation will be hosted at docs.developer.gov.sg. All changes made to your GitHub/GitLab repository would be automatically synced to the documentation portal.

Publishing multiple docs

You can publish multiple documentation from the same repository! Simply repeat Step 1 to 4 of “Publish your documentation with the guided Publishing Wizard” above.

When in the “Document Settings” page, provide a different “Display Name” and “Description”, and ensure a different “HomePage” is selected.

Once the new documentation is published, you will be able to see the new published documentation in docs.developer.gov.sg.

Overview

Diagrams with Mermaid