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.
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.
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.
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/.
Markdown must adhere to the sub/superset supported by Text::MultiMarkdown.
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)
---
Use only level 2 headings and below, since level 1 is used for the document title.
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/