Contribute

How to contribute

Everyone is encouraged to help extend and update the documentation for the frontend docs.

Submit topics or content using the issue tracker https://gitlab.met.no/team-frontend/docs-frontend/-/issues.

Create a pull-request with your contribution to https://gitlab.met.no/team-frontend/docs-frontend.

Layout

The order of the content in the sidebar is organized in toc (table of content) structure, defined in index.rst.

The content of the sidebar should be organized in this hierarchical structure.

CONTAINERS

Introduction

Concepts

Guides

FAQ

KUBERNETES

Introduction

Workflow

Concepts

Guides

Tools

Operators

FAQ

CONTRIBUTE.

Note

Keep the topics as short and descriptive as possible for easy overview.

Writing guide

Outline

Introduction, including links to the main topics in that follows.
Content, remember to include examples and figures wherever it makes sense.

General

Interactive content, Internal and External Links to external or internal topics mentioned.
Avoid unexplained acronyms.
Simple language is processed faster than academic.
Done is better than perfect.

Syntax

Sphinx by default uses RST (reStructuredText) for it’s content. In this section you can expect to find basic examples, as with any another plain text formatting markup language, there exists a RST/Sphinx cheat sheet.

Please refer to the Official documentation for topics not mentioned here.

Headers

In order to write a title, just underline it:

=====
Title
=====

subtitle
--------

Two rules:

use at least as many characters as the length of the title

characters usage is quite flexible but be consistent

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings.

# with overline, for parts
* with overline, for chapters
=, for sections
-, for subsections
^, for subsubsections
“, for paragraphs

example:

#####
Parts
#####

*******
Chapter
*******

Section
=======

Subsection
----------

Subsubsection
^^^^^^^^^^^^^

Paragraph
"""""""""

Internal and External Links

Internal hyperlinks

All titles are considered as internal hyperlinks that may be refered to using this syntax:

`Internal and External links`_

You may also create hyperlink as follows:

.. _begin:

And then inserting begin_ in your text. For instance, jump to the beginning of this document contribute

Note

Note the underscore at the end ot the links

External links

In order to link to external links simply use:

`Python <http://www.python.org/>`_

that is rendered as a normal hyperlink Python.

Note

If you have an underscore within the label/name, you got to escape it with a ‘\’ character.

list and bullets

The following code:

* This is a bulleted list.
* It has two items, the second
  item uses two lines. (note the indentation)

1. This is a numbered list.
2. It has two items too.

#. This is a numbered list.
#. It has two items too.

gives:

This is a bulleted list.
It has two items, the second item uses two lines. (note the indentation)

This is a numbered list.
It has two items too.
This is a numbered list.
It has two items too.

Note

if two lists are separated by a blanck line only, then the two lists are not differentiated as you can see above.