Writing the Documentation

This page shows the constructs that the documentation site of a gCube service supports, each as it renders, so that a service copying this template sees what works. The rules behind them are in the guide of d4science-service-docs, “What a Component Does”: https://code-repo.d4science.org/gCubeSystem/d4science-service-docs/src/branch/master/documentation/usage.md.

The Sources

The pages are Markdown (CommonMark) in documentation/, starting from index.md, which lists the other pages in a hidden toctree. The landing page of the service has its own sections in documentation/landing/, which are not pages of this site:

| File | Section of the landing page | | — | — | | welcome.md | The welcome, with the key indicators named in its front matter | | users.md | Intended users | | functions.md | Primary functions | | responsibility.md | Owner, Operator and Organisation |

After every edit, run the formatter from the root of the component and look at the diff:

mvn -q initialize exec:exec@d4s-docs-format

Tables

A table is written in the GitHub style, with a blank line before and after it. A | inside a cell is written \|, also inside a code span:

| Path | Token | Example of a value with a pipe | | — | — | — | | /hello | required | a\|b | | /guest | none | x\|y |

Math

Inline math is written between single dollars, such as the greetings counted in an interval, \(g = n_{end} - n_{start}\), and an equation of its own between double dollars, all on one line:

\[r = \frac{g}{\Delta t}\]

Diagrams

A Mermaid diagram is a code block of language mermaid. This one is a call to /hello:

sequenceDiagram
    participant C as Client
    participant S as SmartGears
    participant H as Hello World Service
    C->>S: GET /hello-world-service/hello (Bearer token)
    S->>S: verify the token, set the Context
    S->>H: the request, with the caller and the Context
    H-->>C: the greeting

HTTP Requests

An http code block names the protocol on its request line, or it cannot be highlighted:

GET /hello-world-service/hello HTTP/1.1
Authorization: Bearer <token>