weatherapi-docs

weatherapi-docs

Documentation for api.met.no

#markdown#jekyll#schemas
Download

MET WeatherAPI documentation documentation

This repo contains (at some point in the future) most of the docs on api.met.no which are not autogenerated from module POD or metadata.

The content is designed primarily to be shown at https://api.met.no/doc/, but is (unofficially) also visible for development purposes at https://docs.api.met.no/.

It is also possible to add documents here intended for export to the Yr Developer Portal.

Organization

Structure the information according to the Divio Documentation System. Documentation should fall into one of the following categories:

Tutorials

  • Purpose: learning
  • Aim: allow the newcomer to get started

How-to guides

  • Purpose: step-by-step instructions
  • Aim: show how to solve a specific problem

Reference

  • Purpose: looking up specific information
  • Aim: describe the machinery

Explanation

  • Purpose: deeper understanding
  • Aim: explain complex problems

All articles should be marked with the corresponding tag in the YAML preamble.

File structure

The files are organized as illustrated:

    weatherapi-docs/
    ├── doc
    │   ├── assets
    │   ├── locationforecast
    │   ├── metalerts
    │   ├── nowcast
    │   ├── oceanforecast
    │   └── sunrise
    ├── _layouts
    ├── _posts
    ├── products
    ├── schemas
    ├── _site
    └── README.md

This is a typical Jekyll structure, with blog articles in _posts, HTML templates in _layouts and so on. The _site folder is used by Jekyll for auto-generating HTML and is excluded in .gitignore.

API static documentation pages shown under https://api.met.no/doc/ on api.met.no reside in the doc directory. All files here must be in Markdown format, except for assets where you can put PDFs, images etc. (this is a limitation of WeatherAPI, not on GitHub/Jekyll).

Files which are not intended to be processed as Markdown but still included in WeatherAPI may be stored in other directories. E.g. schemas contain the XML schemas used on schema.api.met.no, while products is used to show non-WeatherAPI products on api.met.no. This may be added to in the future, e.g. for microservice metadata.

Running Jekyll

First you must install Jekyll as per the instructions.

To view the documentation locally, start Jekyll:

$ ./site run

You can then open your local version on http://localhost:4000/.

Format

Markdown must adhere to the sub/superset supported by Text::MultiMarkdown.

YAML preamble

All documentation must start with metadata in YAML format, like this:

---
title: Heading of document (do not write this in the body text)
date: when you wrote it
author: your name
layout: page (for docs) or post (for blog)
summary: >
    A short description of the subject matter (used on developer.yr.no)
---

Headings

Use only level 2 headings and below, since level 1 is used for the document title.

Code blocks

For some reason, grave-defined blocks don't work in the API, use 4-space indents instead. Also we have not implemented syntax highlighting, so there is no point in using the former.

# this works

    {
        "foo": "bar"
    }

# this doesn't

```json
{
    "foo": "bar"
}
```

Do not write "click here for more information" as it is considered bad practice.

Since text can be displayed under many different subdomains, all links must be root-relative, e.g.

... see [locationforecast](/weatherapi/locationforecast/2.0/) for info.

Exceptions:

  • Stand-alone tutorials refering to the API product page can use absolute URLs to api.met.no

All content not explicitly specified otherwise is licenced by the NLOD and CC BY 4.0 licences. The full text is included in LICENCE.txt in this repo.

Copyright 2020 The Norwegian Meteorological Institute Henrik Mohns Plass 1, 0371 Oslo https://www.met.no/

minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog