Improved documentation (#1957)

This adds doc pages to the existing API docs. This is similar to the approach of the docs of GoRouter, see for example the following page: https://pub.dev/documentation/go_router/latest/topics/Get%20started-topic.html This works by making use of categories (also called topics). See dartdoc explanation at https://pub.dev/packages/dartdoc#advanced-features ### How to test this Execute `dart doc` in the dio folder. This creates the docs. When opening the index.html, you should see the newly added migration page in the API docs. ### Further stops I'll try to migrate further documentation to, but further I'd like some feedback. ### New Pull Request Checklist - [x] I have read the [Documentation](https://pub.dev/documentation/dio/latest/) - [x] I have searched for a similar pull request in the [project](https://github.com/cfug/dio/pulls) and found none - [x] I have updated this branch with the latest `main` branch to avoid conflicts (via merge from master or rebase) - [ ] I have added the required tests to prove the fix/feature I'm adding - [x] I have updated the documentation (if necessary) - [x] I have run the tests without failures - [ ] I have updated the `CHANGELOG.md` in the corresponding package ### Additional context and info (if any)  Fixes #1921
cfug · Sep 18, 2023 · a20f635 · a20f635
1 parent 5076208
commit a20f635
Show file tree

Hide file tree

Showing 5 changed files with 28 additions and 18 deletions.
diff --git a/dio/README.md b/dio/README.md
@@ -60,7 +60,7 @@ Add the `dio` package to your [pubspec dependencies](https://pub.dev/packages/di
 
 
 **Before you upgrade: Breaking changes might happen in major and minor versions of packages.<br/>
-See the [Migration Guide][] for the complete breaking changes list.**
+See the [Migration Guide](https://pub.dev/documentation/dio/latest/topics/Migration%20Guide-topic.html) for the complete breaking changes list.**
 
 ### Super simple to use
 
@@ -81,22 +81,7 @@ void getHttp() async {
 
 ### Plugins
 
-<!-- Use https://pub.dev for the hosted URL. -->
-| Repository                                                                                             | Status                                                                                                                       | Description                                                                                                            |
-|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
-| [dio_cookie_manager](https://github.com/cfug/dio/blob/main/plugins/cookie_manager)                     | [![Pub](https://img.shields.io/pub/v/dio_cookie_manager.svg)](https://pub.dev/packages/dio_cookie_manager)                   | A cookie manager for Dio                                                                                               |
-| [dio_http2_adapter](https://github.com/cfug/dio/blob/main/plugins/http2_adapter)                       | [![Pub](https://img.shields.io/pub/v/dio_http2_adapter.svg)](https://pub.dev/packages/dio_http2_adapter)                     | A Dio HttpClientAdapter which support Http/2.0                                                                         |
-| [native_dio_adapter](https://github.com/cfug/dio/blob/main/plugins/native_dio_adapter)                 | [![Pub](https://img.shields.io/pub/v/native_dio_adapter.svg)](https://pub.dev/packages/native_dio_adapter)                   | An adapter for Dio which makes use of cupertino_http and cronet_http to delegate HTTP requests to the native platform. |
-| [dio_smart_retry](https://github.com/rodion-m/dio_smart_retry)                                         | [![Pub](https://img.shields.io/pub/v/dio_smart_retry.svg)](https://pub.dev/packages/dio_smart_retry)                         | Flexible retry library for Dio                                                                                         |
-| [http_certificate_pinning](https://github.com/diefferson/http_certificate_pinning)                     | [![Pub](https://img.shields.io/pub/v/http_certificate_pinning.svg)](https://pub.dev/packages/http_certificate_pinning)       | Https Certificate pinning for Flutter                                                                                  |
-| [dio_intercept_to_curl](https://github.com/blackflamedigital/dio_intercept_to_curl)                   | [![Pub](https://img.shields.io/pub/v/dio_intercept_to_curl.svg)](https://pub.dev/packages/dio_intercept_to_curl) | A Flutter curl-command generator for Dio.                                                                              |
-| [dio_cache_interceptor](https://github.com/llfbandit/dio_cache_interceptor)                            | [![Pub](https://img.shields.io/pub/v/dio_cache_interceptor.svg)](https://pub.dev/packages/dio_cache_interceptor)             | Dio HTTP cache interceptor with multiple stores respecting HTTP directives (or not)                                    |
-| [dio_http_cache](https://github.com/hurshi/dio-http-cache)                                             | [![Pub](https://img.shields.io/pub/v/dio_http_cache.svg)](https://pub.dev/packages/dio_http_cache)                           | A simple cache library for Dio like Rxcache in Android                                                                 |
-| [pretty_dio_logger](https://github.com/Milad-Akarie/pretty_dio_logger)                                 | [![Pub](https://img.shields.io/pub/v/pretty_dio_logger.svg)](https://pub.dev/packages/pretty_dio_logger)                     | Pretty Dio logger is a Dio interceptor that logs network calls in a pretty, easy to read format.                       |
-| [dio_image_provider](https://github.com/ueman/image_provider)                                          | [![Pub](https://img.shields.io/pub/v/dio_image_provider.svg)](https://pub.dev/packages/dio_image_provider)                   | An image provider which makes use of package:dio to instead of dart:io                                                 |
-| [flutter_ume_kit_dio](https://github.com/cfug/flutter_ume_kits/tree/main/packages/flutter_ume_kit_dio) | [![Pub](https://img.shields.io/pub/v/flutter_ume_kit_dio.svg)](https://pub.dev/packages/flutter_ume_kit_dio)                 | A debug kit of dio on flutter_ume                                                                                      |
-
-### Related Projects
+[Plugins](https://pub.dev/documentation/dio/latest/topics/Plugins-topic.html)
 
 Welcome to submit third-party plugins and related libraries
 in [here](https://github.com/cfug/dio/issues/347).
@@ -910,6 +895,5 @@ and a server is aware using specific methods and headers.
 You can modify your requests to match the definition of simple request,
 or add a CORS middleware for your service to handle CORS requests.
 
-[Migration Guide]: ./migration_guide.md
 [simple request]: https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests
 [CORS preflight request]: https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request
diff --git a/dio/dartdoc_options.yaml b/dio/dartdoc_options.yaml
@@ -0,0 +1,7 @@
+dartdoc:
+  showUndocumentedCategories: true
+  categories:
+    "Migration Guide":
+      markdown: docs/migration_guide.md
+    "Plugins":
+      markdown: docs/plugins.md
diff --git a/dio/migration_guide.md → dio/docs/migration_guide.md b/dio/migration_guide.md → dio/docs/migration_guide.md
diff --git a/dio/docs/plugins.md b/dio/docs/plugins.md
@@ -0,0 +1,17 @@
+# Plugins
+
+<!-- Use https://pub.dev for the hosted URL. -->
+| Repository                                                                                             | Status                                                                                                                       | Description                                                                                                            |
+|--------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------|
+| [dio_cookie_manager](https://github.com/cfug/dio/blob/main/plugins/cookie_manager)                     | [![Pub](https://img.shields.io/pub/v/dio_cookie_manager.svg)](https://pub.dev/packages/dio_cookie_manager)                   | A cookie manager for Dio                                                                                               |
+| [dio_http2_adapter](https://github.com/cfug/dio/blob/main/plugins/http2_adapter)                       | [![Pub](https://img.shields.io/pub/v/dio_http2_adapter.svg)](https://pub.dev/packages/dio_http2_adapter)                     | A Dio HttpClientAdapter which support Http/2.0                                                                         |
+| [native_dio_adapter](https://github.com/cfug/dio/blob/main/plugins/native_dio_adapter)                 | [![Pub](https://img.shields.io/pub/v/native_dio_adapter.svg)](https://pub.dev/packages/native_dio_adapter)                   | An adapter for Dio which makes use of cupertino_http and cronet_http to delegate HTTP requests to the native platform. |
+| [dio_smart_retry](https://github.com/rodion-m/dio_smart_retry)                                         | [![Pub](https://img.shields.io/pub/v/dio_smart_retry.svg)](https://pub.dev/packages/dio_smart_retry)                         | Flexible retry library for Dio                                                                                         |
+| [http_certificate_pinning](https://github.com/diefferson/http_certificate_pinning)                     | [![Pub](https://img.shields.io/pub/v/http_certificate_pinning.svg)](https://pub.dev/packages/http_certificate_pinning)       | Https Certificate pinning for Flutter                                                                                  |
+| [dio_intercept_to_curl](https://github.com/blackflamedigital/dio_intercept_to_curl)                    | [![Pub](https://img.shields.io/pub/v/dio_intercept_to_curl.svg)](https://pub.dev/packages/dio_intercept_to_curl)             | A Flutter curl-command generator for Dio.                                                                              |
+| [dio_cache_interceptor](https://github.com/llfbandit/dio_cache_interceptor)                            | [![Pub](https://img.shields.io/pub/v/dio_cache_interceptor.svg)](https://pub.dev/packages/dio_cache_interceptor)             | Dio HTTP cache interceptor with multiple stores respecting HTTP directives (or not)                                    |
+| [dio_http_cache](https://github.com/hurshi/dio-http-cache)                                             | [![Pub](https://img.shields.io/pub/v/dio_http_cache.svg)](https://pub.dev/packages/dio_http_cache)                           | A simple cache library for Dio like Rxcache in Android                                                                 |
+| [pretty_dio_logger](https://github.com/Milad-Akarie/pretty_dio_logger)                                 | [![Pub](https://img.shields.io/pub/v/pretty_dio_logger.svg)](https://pub.dev/packages/pretty_dio_logger)                     | Pretty Dio logger is a Dio interceptor that logs network calls in a pretty, easy to read format.                       |
+| [dio_image_provider](https://github.com/ueman/image_provider)                                          | [![Pub](https://img.shields.io/pub/v/dio_image_provider.svg)](https://pub.dev/packages/dio_image_provider)                   | An image provider which makes use of package:dio to instead of dart:io                                                 |
+| [flutter_ume_kit_dio](https://github.com/cfug/flutter_ume_kits/tree/main/packages/flutter_ume_kit_dio) | [![Pub](https://img.shields.io/pub/v/flutter_ume_kit_dio.svg)](https://pub.dev/packages/flutter_ume_kit_dio)                 | A debug kit of dio on flutter_ume                                                                                      |
+| [sentry_dio](https://github.com/getsentry/sentry-dart)                                                 | [![Pub](https://img.shields.io/pub/v/sentry_dio.svg)](https://pub.dev/packages/sentry_dio)                                   | An integration which adds support for performance tracing for the Dio package.                                         |
diff --git a/dio/lib/dio.dart b/dio/lib/dio.dart
@@ -1,6 +1,8 @@
 /// A powerful HTTP client for Dart and Flutter, which supports global settings,
 /// [Interceptors], [FormData], aborting and canceling a request,
 /// files uploading and downloading, requests timeout, custom adapters, etc.
+/// {@category Migration Guide}
+/// {@category Plugins}
 library dio;
 
 export 'src/adapter.dart';