Skip to content

Commit 298ede7

Browse files
cmfcmfcmfcmf
committed
Add documentation using Docusaurus v2
1 parent a08d55a commit 298ede7

20 files changed

+10334
-69
lines changed

‎.gitattributes

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
/docs export-ignore

‎README.md

+22-69
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@ OpenWeatherMap PHP API
22
======================
33
A PHP 7.0+ API to retrieve and parse global weather data from
44
[OpenWeatherMap.org](http://www.OpenWeatherMap.org).
5-
This library aims to normalise the provided data and remove some inconsistencies.
6-
This library is neither maintained by OpenWeatherMap nor their official PHP API.
5+
This project aims to normalise the provided data and remove inconsistencies.
6+
It is not maintained by OpenWeatherMap and not an official API wrapper.
77

88
[![Build Status](https://travis-ci.org/cmfcmf/OpenWeatherMap-PHP-Api.svg?branch=master)](https://travis-ci.org/cmfcmf/OpenWeatherMap-PHP-Api)
99
[![license](https://img.shields.io/github/license/cmfcmf/OpenWeatherMap-PHP-Api.svg)](https://github.com/cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
@@ -13,74 +13,14 @@ This library is neither maintained by OpenWeatherMap nor their official PHP API.
1313
<br>
1414
[![SensioLabsInsight](https://insight.sensiolabs.com/projects/0addfb24-e2b4-4feb-848e-86b2078ca104/big.png)](https://insight.sensiolabs.com/projects/0addfb24-e2b4-4feb-848e-86b2078ca104)
1515

16-
Installation
17-
============
18-
This library can be found on [Packagist](https://packagist.org/packages/cmfcmf/openweathermap-php-api).
19-
The recommended way to install and use it is through [Composer](http://getcomposer.org).
20-
21-
composer require "cmfcmf/openweathermap-php-api"
22-
23-
You will also need to choose and install two additional dependencies separately:
24-
25-
1. A [PSR-17](https://www.php-fig.org/psr/psr-17/) compatible HTTP factory implementation.
26-
A list of HTTP factory implementations is available at
27-
[Packagist](https://packagist.org/providers/psr/http-factory-implementation).
28-
2. A [PSR-18](https://www.php-fig.org/psr/psr-18/) compatible HTTP client implementation.
29-
A list of HTTP client implementations is available at
30-
[Packagist](https://packagist.org/providers/psr/http-client-implementation).
31-
32-
Example call
33-
============
34-
```php
35-
<?php
36-
use Cmfcmf\OpenWeatherMap;
37-
use Cmfcmf\OpenWeatherMap\Exception as OWMException;
38-
use Http\Factory\Guzzle\RequestFactory;
39-
use Http\Adapter\Guzzle6\Client as GuzzleAdapter;
40-
41-
// Must point to composer's autoload file.
42-
require 'vendor/autoload.php';
43-
44-
// Language of data (try your own language here!):
45-
$lang = 'de';
46-
47-
// Units (can be 'metric' or 'imperial' [default]):
48-
$units = 'metric';
49-
50-
// You can use every PSR-17 compatible HTTP request factory
51-
// and every PSR-18 compatible HTTP client. This example uses
52-
// `http-interop/http-factory-guzzle` ^1.0 and `php-http/guzzle6-adapter` ^2.0 || ^1.0
53-
// which you need to install separately.
54-
$httpRequestFactory = new RequestFactory();
55-
$httpClient = GuzzleAdapter::createWithConfig([]);
56-
57-
// Create OpenWeatherMap object.
58-
$owm = new OpenWeatherMap('YOUR-API-KEY', $httpClient, $httpRequestFactory);
59-
60-
try {
61-
$weather = $owm->getWeather('Berlin', $units, $lang);
62-
} catch(OWMException $e) {
63-
echo 'OpenWeatherMap exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
64-
} catch(\Exception $e) {
65-
echo 'General exception: ' . $e->getMessage() . ' (Code ' . $e->getCode() . ').';
66-
}
67-
68-
echo $weather->temperature;
69-
```
16+
Documentation
17+
=============
7018

71-
For more example code and instructions on how to use this library, please take
72-
a look into the `Examples` folder. Make sure to get an API Key from
73-
http://home.openweathermap.org/ and put it into `Examples/ApiKey.ini`.
74-
75-
- `CurrentWeather.php` shows how to receive the current weather.
76-
- `WeatherForecast.php` shows how to receive weather forecasts.
77-
- `UVIndex.php` shows how to receive uv index data.
78-
- `AirPollution.php` show how to receive air pollution data.
19+
You can find the latest documentation, including installation and usage instructions at https://cmfcmf.github.io/OpenWeatherMap-PHP-API.
7920

8021
Contributing
8122
============
82-
I'm happy about every **pull request** or **issue** you find and open to help
83-
make this API **more awesome**.
23+
I'm happy about every **pull request** you open and **issue** you find to help make this API **more awesome**. Please note that it might sometimes take me a while to get back to you. Feel free to ping me if I don't respond.
8424

8525
## Vagrant
8626

@@ -105,13 +45,26 @@ And then execute an example:
10545

10646
> php Examples/CurrentWeather.php
10747

48+
## Documentation
49+
50+
The documentation is built using [Docusuaurs v2](https://v2.docusaurus.io/).
51+
To run a local developnment server for the docs, execute
52+
53+
```bash
54+
cd docs
55+
yarn install
56+
yarn start
57+
```
10858

10959
License
11060
=======
111-
MIT — Please see the [LICENSE file](https://github.com/Cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
61+
62+
This project is licensed under the MIT license.
63+
Please see the [LICENSE file](https://github.com/Cmfcmf/OpenWeatherMap-PHP-Api/blob/master/LICENSE)
11264
distributed with this source code for further information regarding copyright and licensing.
11365

114-
**Please check out the following official links to read about the terms, pricing
115-
and license of OpenWeatherMap before using the service:**
66+
Be aware that the OpenWeatherMap data is **not licensed under the MIT**.
67+
**Check out the following official links to read about the terms, pricing and license of OpenWeatherMap before using their service:**
68+
11669
- [OpenWeatherMap.org/terms](http://OpenWeatherMap.org/terms)
11770
- [OpenWeatherMap.org/appid](http://OpenWeatherMap.org/appid)

‎docs/.gitignore

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Dependencies
2+
/node_modules
3+
4+
# Production
5+
/build
6+
7+
# Generated files
8+
.docusaurus
9+
.cache-loader
10+
11+
# Misc
12+
.DS_Store
13+
.env.local
14+
.env.development.local
15+
.env.test.local
16+
.env.production.local
17+
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*

‎docs/README.md

+33
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
# Website
2+
3+
This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator.
4+
5+
### Installation
6+
7+
```
8+
$ yarn
9+
```
10+
11+
### Local Development
12+
13+
```
14+
$ yarn start
15+
```
16+
17+
This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.
18+
19+
### Build
20+
21+
```
22+
$ yarn build
23+
```
24+
25+
This command generates static content into the `build` directory and can be served using any static contents hosting service.
26+
27+
### Deployment
28+
29+
```
30+
$ GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
31+
```
32+
33+
If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

‎docs/docs/api-key.md

+21
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: API Key
3+
---
4+
5+
All requests require a free API key (sometimes called "APPID") from OpenWeaterMap.
6+
To retrieve your API key, [sign up for an OpenWeatherMap account](https://home.openweathermap.org/users/sign_up).
7+
8+
After you received your API key, **it might take a ["couple of hours"](https://openweathermap.org/appid) for it to be activated! Other users [reported](https://github.com/cmfcmf/OpenWeatherMap-PHP-API/issues/46) that it took about 10 minutes** until the API key worked.
9+
10+
Please also take note of the license OpenWeatherMap provides the data under. At the time of
11+
writing, all data is licensed under the **CC BY-SA 4.0**, even for paid accounts. However,
12+
remember that this project is not affiliated with OpenWeatherMap, this information may be
13+
outdated and I can't give you legal advice. Make sure to check on the terms and conditions
14+
yourself:
15+
16+
- https://openweathermap.org/terms
17+
- https://openweathermap.org/price
18+
19+
*If something with your API key or account does not work as expected,
20+
please [contact OpenWeatherMap directly](https://openweathermap.force.com/s/contactsupport)
21+
instead of opening an issue, since I most likely cannot help you with your account.*

‎docs/docs/apis/air-pollution.md

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Air Pollution API
3+
sidebar_label: 'API: Air Pollution'
4+
---
5+
6+
This API allows you to retrieve the current, forecast and historic ultraviolet index (UV index).
7+
8+
> Corresponding OpenWeatherMap documentation:
9+
>
10+
> - [Carbon Monoxide (CO)](https://openweathermap.org/api/pollution/co)
11+
> - [Ozone (O3)](https://openweathermap.org/api/pollution/o3)
12+
> - [Nitrogen Dioxide (NO2)](https://openweathermap.org/api/pollution/no2)
13+
> - [Sulfor Dioxide (SO2)](https://openweathermap.org/api/pollution/so2)
14+
15+
## Usage
16+
17+
- `$type`: Can be one of `"O3"`, `"NO2"`, `"SO2"`, or `"CO"`.
18+
- `$lat` / `$lng`: Latitude and longitude must be provided as strings, because
19+
the number of digits after the decimal point determines the search radius.
20+
Specifying more digits leads to closer results, but too many digits can lead
21+
to no result at all.
22+
- `$date`: Date to retrieve data from. `"current"` requests the newest available
23+
information. You can also specify a date in ISO 8601 format. More information on
24+
that can be found [in the OpenWeatherMap documentation](https://openweathermap.org/api/pollution/co).
25+
26+
```php
27+
// $type =
28+
$co = $owm->getAirPollution($type, $lat, $lng, $date = "current");
29+
```
30+
31+
The return value depends on the `$type` and is discussed in the next sections.
32+
33+
### Carbon Monoxide (CO)
34+
35+
```php
36+
$co = $owm->getAirPollution("CO", "52", "13");
37+
if ($co === null) {
38+
// No data available
39+
} else {
40+
foreach ($co->values as $data) {
41+
echo $data["value"];
42+
echo $data["value"]->getPrecision();
43+
echo $data["pressure"];
44+
}
45+
}
46+
```
47+
48+
### Ozone (O3)
49+
50+
```php
51+
$o3 = $owm->getAirPollution("O3", "52", "13");
52+
if ($o3 === null) {
53+
// No data available
54+
} else {
55+
echo $o3->value;
56+
}
57+
```
58+
59+
### Nitrogen Dioxide (NO2)
60+
61+
```php
62+
$no2 = $owm->getAirPollution("NO2", "52", "13");
63+
if ($no2 === null) {
64+
// No data available
65+
} else {
66+
echo $no2->value;
67+
echo $no2->valueStratosphere;
68+
echo $no2->valueTroposphere;
69+
}
70+
```
71+
72+
### Sulfor Dioxide (SO2)
73+
74+
```php
75+
$so2 = $owm->getAirPollution("SO2", "52", "13");
76+
if ($so2 === null) {
77+
// No data available
78+
} else {
79+
foreach ($so2->values as $data) {
80+
echo $data["value"];
81+
echo $data["value"]->getPrecision();
82+
echo $data["pressure"];
83+
}
84+
}
85+
```

0 commit comments

Comments
 (0)