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>

Links¶

A link to another page is written to its Markdown file, with a fragment for a heading: the authorization of this service. The other surfaces of the service (the REST API documentation, the landing page) are reached from the menu at the top right.