From a20f63570508e3892030a7981300709f6fe823bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jonas=20Uek=C3=B6tter?= Date: Mon, 18 Sep 2023 10:42:30 +0200 Subject: [PATCH] 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 --- dio/README.md | 20 ++------------------ dio/dartdoc_options.yaml | 7 +++++++ dio/{ => docs}/migration_guide.md | 0 dio/docs/plugins.md | 17 +++++++++++++++++ dio/lib/dio.dart | 2 ++ 5 files changed, 28 insertions(+), 18 deletions(-) create mode 100644 dio/dartdoc_options.yaml rename dio/{ => docs}/migration_guide.md (100%) create mode 100644 dio/docs/plugins.md diff --git a/dio/README.md b/dio/README.md index 38133b185..b2ba69d01 100644 --- 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.
-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 - -| 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 new file mode 100644 index 000000000..9455461ab --- /dev/null +++ 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 b/dio/docs/migration_guide.md similarity index 100% rename from dio/migration_guide.md rename to dio/docs/migration_guide.md diff --git a/dio/docs/plugins.md b/dio/docs/plugins.md new file mode 100644 index 000000000..400133ada --- /dev/null +++ b/dio/docs/plugins.md @@ -0,0 +1,17 @@ +# Plugins + + +| 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 index 1a4a5bafa..60c9044c8 100644 --- 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';