# 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:

```sh
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

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

```eval_rst
.. math::

   r = \frac{g}{\Delta t}
```

## Diagrams

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

```mermaid
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:

```http
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](index.html#authorization). The other surfaces of the service
(the REST API documentation, the landing page) are reached from the menu at the top right.
