Skip to content

Commit 2ff8579

Browse files
pyrechpyrech
committed
Change docs structure
1 parent a1e0057 commit 2ff8579

File tree

9 files changed

+123
-22
lines changed

9 files changed

+123
-22
lines changed

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ $client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
4040
$user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
4141
```
4242

43-
Want more documentation or examples? See the [full documentation here](https://jolicode.github.io/slack-php-api/#/docs/usage).
43+
Want more documentation or examples? See the [full documentation here](https://jolicode.github.io/slack-php-api/).
4444

4545
## Further documentation
4646

‎docs/1-get-started.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Getting started
2+
3+
## Installation
4+
5+
This library is built atop of [PSR-7](https://www.php-fig.org/psr/psr-7/) and
6+
[PSR-18](https://www.php-fig.org/psr/psr-18/). So you will need to install some
7+
implementations for those standard interfaces.
8+
9+
If no PSR-18 client or PSR-7 message factory is available yet in your project
10+
or you don't know or don't care which one to use, just install some default:
11+
12+
```bash
13+
composer require symfony/http-client nyholm/psr7
14+
```
15+
16+
You can now install the Slack client:
17+
18+
```bash
19+
composer require jolicode/slack-php-api
20+
```
21+
22+
## Quick start
23+
24+
```php
25+
// $client contains all the methods to interact with the API
26+
$client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
27+
28+
$user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
29+
```
30+
31+
***
32+
33+
Read more:
34+
- Next page: [Usage](2-usage.md)
35+
- Previous page: [Introduction](index.md)

docs/usage.md renamed to docs/2-usage.md

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Usage documentation
1+
# Usage
22

33
## Slack token
44

@@ -82,18 +82,22 @@ Here are some real-life examples of interacting with the SDK:
8282

8383
## Under the hood
8484

85-
This library mostly contains automatically generated code from the official
85+
This library mainly contains automatically generated code from the official
8686
[Slack OpenAPI spec](https://github.com/slackapi/slack-api-specs).
8787

88-
The library provides three kinds of PHP classes:
89-
- [endpoints](https://github.com/jolicode/slack-php-api/tree/main/generated/Endpoint) represent requests to API methods
90-
- [models](https://github.com/jolicode/slack-php-api/tree/main/generated/Model) represent data from the API
91-
- [normalizers](https://github.com/jolicode/slack-php-api/tree/main/generated/Normalizer) transform JSON from the API to PHP models
88+
Four kinds of PHP classes are included:
89+
- [endpoints](https://github.com/jolicode/slack-php-api/tree/main/generated/Endpoint) represent the requests made to API methods;
90+
- [models](https://github.com/jolicode/slack-php-api/tree/main/generated/Model) represent data exchanged with the API;
91+
- [normalizers](https://github.com/jolicode/slack-php-api/tree/main/generated/Normalizer) transform JSON from the API to PHP models;
92+
- [runtime](https://github.com/jolicode/slack-php-api/tree/main/generated/Runtime) are classes needed to make Jane work.
9293

93-
If you use the `JoliCode\Slack\ClientFactory` to create the Client, you don't
94-
have to understand how the library works internally. Calling one of its method
95-
will make the HTTP request to the API and return the corresponding PHP object.
94+
If you use the `JoliCode\Slack\ClientFactory` to create the Client (which you
95+
should), you don't have to understand how the library works internally.
96+
Calling one of its method will make the HTTP request to the API and return the
97+
corresponding PHP object.
9698

97-
## Troubleshoots
99+
***
98100

99-
Got some problems using this library? Need a missing feature? See the dedicated guide [about common troubleshoots](troubleshoots.md).
101+
Read more:
102+
- Next page: [Troubleshoots](3-troubleshoots.md)
103+
- Previous page: [Get started](1-get-started.md)

docs/troubleshoots.md renamed to docs/3-troubleshoots.md

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Troubleshoots
22

3+
Got some problems using this library? Need a missing feature?
4+
Here is some common troubleshoots.
5+
36
## Bypassing the incomplete API specification
47

58
Slack's OpenAPI spec is not 100% complete yet, hence our generated client may
@@ -34,3 +37,9 @@ Feel free to open issues if you think a model miss some fields.
3437

3538
The above documentation did not answer your question? Do not hesitate to open
3639
an issue and share your issue with us.
40+
41+
***
42+
43+
Read more:
44+
- Next page: [Updating the SDK](4-updating-sdk.md)
45+
- Previous page: [Usage](2-usage.md)

docs/updating-sdk.md renamed to docs/4-updating-sdk.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,9 @@ changes, you can check that the patch is correctly re-applied:
5656
```bash
5757
./bin/slack-api-client-generator spec:update
5858
```
59+
60+
***
61+
62+
Read more:
63+
- Next page: [Changelog](/changelog)
64+
- Previous page: [Troubleshoots](3-troubleshoots.md)

‎docs/_sidebar.md‎

Lines changed: 0 additions & 8 deletions
This file was deleted.

‎docs/index.html‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
<!DOCTYPE html>
2+
<html>
3+
<head>
4+
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
5+
<meta name="viewport" content="width=device-width,initial-scale=1">
6+
<meta charset="UTF-8">
7+
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />
8+
</head>
9+
<body>
10+
<div id="app"></div>
11+
<script>
12+
window.$docsify = {
13+
name: 'slack-php-api',
14+
repo: 'jolicode/slack-php-api',
15+
relativePath: true,
16+
loadSidebar: 'navigation.md',
17+
homepage: 'index.md',
18+
themeColor: '#ecb22e',
19+
auto2top: true,
20+
alias: {
21+
'/docs/(.*)': '/$1.md', // supports regexp
22+
'/changelog': 'https://raw.githubusercontent.com/jolicode/slack-php-api/main/CHANGELOG.md',
23+
},
24+
}
25+
</script>
26+
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
27+
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
28+
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-php.min.js"></script>
29+
</body>
30+
</html>

‎docs/index.md‎

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,22 @@
1-
Here is the documentation of jolicode/slack-php-api
1+
# Introduction
22

3-
Start by reading [the introduction](../README.md).
3+
Welcome on the documentation of jolicode/slack-php-api.
4+
5+
This library is a **PHP client** for **Slack's Web API**.
6+
7+
## About this SDK
8+
9+
There is a bunch of existing PHP clients for Slack. But some are not up to date
10+
or miss features, some only cover a small part of the API and most are simply
11+
no longer maintained.
12+
13+
This SDK is generated automatically with [JanePHP](https://github.com/janephp/janephp)
14+
from the [official Slack API specs](https://github.com/slackapi/slack-api-specs).
15+
16+
It also provides a **full object oriented interface** for all the endpoints,
17+
requests and responses of the Slack Web API.
18+
19+
***
20+
21+
Read more:
22+
- Next page: [Get started](1-get-started.md)

‎docs/navigation.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
* [Introduction](/)
2+
* [Get started](1-get-started)
3+
* [Usage](2-usage.md)
4+
* [Troubleshoots](3-troubleshoots.md)
5+
* [Updating the SDK](4-updating-sdk.md)
6+
* [Changelog](/changelog)

0 commit comments

Comments
 (0)