Improve the documentation

Author: pyrech

.php_cs

@@ -36,7 +36,7 @@ return PhpCsFixer\Config::create()
     ))
     ->setFinder(PhpCsFixer\Finder::create()
         ->in(__DIR__)
-        ->exclude('doc')
+        ->exclude('docs')
         ->exclude('ci_generated')
     )
 ;

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 * Add a new Client to ease iteration over Slack paginated endpoints thanks to `iterateXxxx` methods (where `xxxx` is the endpoint name to iterate over)
+* Improve the documentation
 
 ## 4.1.1 (2021-03-16)
 

README.md

@@ -1,19 +1,22 @@
-# A PHP client for Slack's API
+# Introduction
 
-There is a bunch of PHP clients for Slack. But some are not up to date or miss
-features, some only cover a small part of the API and most are simply no longer
-maintained.
+This library is a **PHP client** for **Slack's Web API**.
+
+There is a bunch of existing PHP clients for Slack. But some are not up to date
+or miss features, some only cover a small part of the API and most are simply
+no longer maintained.
 
 This SDK is generated automatically with [JanePHP](https://github.com/janephp/janephp)
 from the [official Slack API specs](https://github.com/slackapi/slack-api-specs). 
 
-It provides a **full object oriented interface** for all the endpoints, requests and responses of the Slack Web API.
+It also provides a **full object oriented interface** for all the endpoints,
+requests and responses of the Slack Web API.
 
 ## Installation
 
 This library is built atop of [PSR-7](https://www.php-fig.org/psr/psr-7/) and
 [PSR-18](https://www.php-fig.org/psr/psr-18/). So you will need to install some
-implementations for those interfaces.
+implementations for those standard interfaces.
 
 If no PSR-18 client or PSR-7 message factory is available yet in your project
 or you don't know or don't care which one to use, just install some default:
@@ -28,35 +31,16 @@ You can now install the Slack client:
 composer require jolicode/slack-php-api
 ```
 
-## Usage
-
-First, you need to retrieve a token from Slack. 
-
-Checkout Slack's documentation about [all different kind of tokens](https://api.slack.com/authentication/token-types).
-A good starting point is the [Authentication Basics documentation](https://api.slack.com/authentication/basics).
-
-Then, use the factory that is provided to create the client:
+## Quick start
 
 ```php
 // $client contains all the methods to interact with the API
-$client = JoliCode\Slack\ClientFactory::create($yourToken);
+$client = JoliCode\Slack\ClientFactory::create($yourSlackToken);
 
 $user = $client->usersInfo(['user' => 'U123AZER'])->getUser();
-
-dump($user);
 ```
 
-<p align="center">
-  <img src="doc/images/model-sample.png" alt="Sample user object" />
-<p>
-
-Want more example or documentation? See the [full documentation here](doc/index.md).
-
-## Troubleshoots
-
-Got some problems using this library? Need a missing feature?
-Do not hesitate to [open an issue](https://github.com/jolicode/slack-php-api/issues)
-and share it with us.
+Want more documentation or examples? See the [full documentation here](https://jolicode.github.io/slack-php-api/#/docs/usage).
 
 ## Further documentation
 

doc/images/model-sample.png

@@ -0,0 +1,8 @@
+# Documentation
+
+* [Home](/)
+* [Introduction](/introduction)
+* [Usage](/docs/usage)
+* [Troubleshoots](/docs/troubleshoots)
+* [Updating the SDK](/docs/updating-sdk)
+* [Changelog](/CHANGELOG)

doc/index.md

@@ -0,0 +1,3 @@
+Here is the documentation of jolicode/slack-php-api
+
+Start by reading [the introduction](../README.md).

docs/_sidebar.md

@@ -0,0 +1,36 @@
+# Troubleshoots
+
+## Bypassing the incomplete API specification
+
+Slack's OpenAPI spec is not 100% complete yet, hence our generated client may
+miss some features.
+
+If you miss an option in a method, until Slack add it to their spec, we can
+manually add it to our [versioned spec](https://github.com/jolicode/slack-php-api/tree/main/resources/slack-openapi-patched.json) then
+[regenerate](updating-sdk.md) and release a new version of the library.
+
+## Missing data in the DTO?
+
+The Slack specification is not up to date and miss some critical parts. We do
+build a [better one on top of the official](doc/updating-sdk.md) but it can't
+be perfect.
+
+What's good is that some models use `\ArrayObject` as base classes so if the
+API returns data we don't have in the OpenAPI mapping, you can still access it via
+Array like syntax:
+
+```php
+$results = $client->searchMessages([
+    'query' => 'test'
+]);
+
+var_dump($results->getOk()); // ok property is mapped
+var_dump($results['messages']); // messages property is not mapped but still readable
+```
+
+Feel free to open issues if you think a model miss some fields.
+
+## Other problems?
+
+The above documentation did not answer your question? Do not hesitate to open
+an issue and share your issue with us.