From e863a539bf049a320b6da239c9862f830021d98b Mon Sep 17 00:00:00 2001 From: Ellet Date: Fri, 14 Jun 2024 12:53:05 +0300 Subject: [PATCH] docs(markdown-files): improve markdown docs files --- CONTRIBUTING.md | 53 +++++++++++------- doc/configurations/custom_buttons.md | 3 +- doc/configurations/font_size.md | 8 ++- doc/configurations/localizations_setup.md | 11 +++- doc/configurations/using_custom_app_widget.md | 8 ++- doc/custom_embed_blocks.md | 24 +++++--- doc/custom_toolbar.md | 5 +- doc/development_notes.md | 26 ++++++--- doc/todo.md | 55 ------------------- doc/translation.md | 32 +++++++---- 10 files changed, 117 insertions(+), 108 deletions(-) delete mode 100644 doc/todo.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3f884bd6..bdf2dbbd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,19 +2,26 @@ First of all, we would like to thank you for your time and efforts on this project, we appreciate it -You can see tutorials online on how to contribute to any open source project, it's a simple process, and you can do it even if you are not Git expert, simply start by forking the repository, clone it, creating a new branch, make your changes and commit them, then push the branch to your fork, and you will get link to send a PR to the upstream repository +You can see tutorials online on how to contribute to any open source project, it's a simple process, and you can do it +even if you are not Git expert, simply start by forking the repository, clone it, create a new branch, make your +changes and commit them, then push the branch to your fork, and you will get link to send a PR to the upstream +repository -If you don't have anything specific in mind to improve or fix, you can take a look at the issues tab or take a look at the todos of the project, they all start with `TODO:` so you can search in your IDE or use the todos tab in the IDE +If you don't have anything specific in mind to improve or fix, you can take a look at the issues tab or take a look at +the todos of the project, they all start with `TODO:` so you can search in your IDE or use the todos tab in the IDE -You can also check the [Todo](./doc/todo.md) list or the issues if you want to +You can also check the [Todo](./doc/todo.md) list or the issues if you want to -> Make sure to not edit the `CHANGELOG.md` or the version in `pubspec.yaml` for any of the packages, this process will be automated by CI. +> Make sure to not edit the `CHANGELOG.md` or the version in `pubspec.yaml` for any of the packages, CI will automate +> this process. ## Requirements -- [Flutter SDK](https://docs.flutter.dev/get-started/install) which can be installed by following the instructions the provided link, also make sure to add it to your path so `flutter --version` and `dart --version` work -- [Intellij IDEA Community Edition](https://www.jetbrains.com/idea/download/) or [Android Studio](https://developer.android.com/studio) (with Dart and Flutter plugins) or use [VS Code](https://code.visualstudio.com/) (with Dart and flutter extensions) - +- [Flutter SDK](https://docs.flutter.dev/get-started/install), which can be installed by following the instructions the + provided link, also make sure to add it to your path so `flutter --version` and `dart --version` work +- [IntelliJ IDEA Community Edition](https://www.jetbrains.com/idea/download/) + or [Android Studio](https://developer.android.com/studio) (with Dart and Flutter plugins) or + use [VS Code](https://code.visualstudio.com/) (with Dart and flutter extensions) ## Test your changes 🧪 @@ -22,8 +29,10 @@ Make sure you have the [Requirement](#requirements) installed and configured cor To test your changes: -1. Go to the [Example project](./example/) in [main.dart](./example/lib/main.dart) and run the project either by using your IDE or `flutter run` -2. Make sure to read the [Development Notes](./doc/development_notes.md) if you made certain changes or [Translations Page](./doc/translation.md) if you made changes to the translations of the package +1. Go to the [Example project](./example/) in [main.dart](./example/lib/main.dart) and run the project either by using + your IDE or `flutter run` +2. Make sure to read the [Development Notes](./doc/development_notes.md) if you made certain changes + or [Translations Page](./doc/translation.md) if you made changes to the translations of the package ## Steps to contributing @@ -35,24 +44,29 @@ You will need a GitHub account as well as Git installed and configured with your ``` git remote add upstream git@github.com:singerdmx/flutter-quill.git ``` -4. Open the project with your favorite IDE, usually, we prefer to use Jetbrains IDEs, but since [VS Code](https://code.visualstudio.com) is more used and has more support for Dart, then we suggest using it if you want to. +4. Open the project with your favorite IDE, usually, we prefer to use Jetbrains IDEs, but + since [VS Code](https://code.visualstudio.com) is more used and has more support for Dart, then we suggest using it + if you want to. 5. Create a new git branch and switch to it using `git checkout -b` 6. Make your changes -7. If you are working on changes that depend on different libraries in the same repo, then in that directory copy `pubspec_overrides.yaml.disabled` which exists in all the packages (`flutter_quill_test` and `flutter_quill_extensions` etc...) -to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be used by dart pub to override the libraries +7. If you are working on changes that depend on different libraries in the same repo, then in that directory + copy `pubspec_overrides.yaml.disabled` which exists in all the packages (`flutter_quill_test` + and `flutter_quill_extensions` etc...) + to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be used by dart pub to override the + libraries ``` cp pubspec_overrides.yaml.disabled pubspec_overrides.yaml ``` - or save some time with the following script: + or save some time with the following script: ``` ./scripts/enable_local_dev.sh ``` 8. Test them in the [example](./example) and add changes in there if necessary -9. Run the following script if possible - ``` - ./scripts/before_push.sh - ``` +9. Run the following script if possible + ``` + ./scripts/before_push.sh + ``` 10. When you are done sending your pull request, run: ``` git add . @@ -62,10 +76,11 @@ to `pubspec_overrides.yaml` which will be ignored by `.gitignore` and will be us this will push the new branch to your forked repository 11. Now you can send your pull request either by following the link that you will get in the command line or open your -forked repository. You will find an option to send the pull request, you can also -open the [Pull Requests](https://github.com/singerdmx/flutter-quill) tab and send new pull request + forked repository. You will find an option to send the pull request, you can also + open the [Pull Requests](https://github.com/singerdmx/flutter-quill) tab and send new pull request 12. Now, wait for the review, and we might ask you to make more changes, then run: + ``` git add . git commit -m "Your new commit message" diff --git a/doc/configurations/custom_buttons.md b/doc/configurations/custom_buttons.md index 24f9e1ca..1b52c25f 100644 --- a/doc/configurations/custom_buttons.md +++ b/doc/configurations/custom_buttons.md @@ -1,6 +1,7 @@ # Custom `QuillToolbar` Buttons -You may add custom buttons to the _end_ of the toolbar, via the `customButtons` option, which is a `List` of `QuillToolbarCustomButtonOptions`. +You may add custom buttons to the _end_ of the toolbar, via the `customButtons` option, which is a `List` +of `QuillToolbarCustomButtonOptions`. To add an Icon, we should use a new `QuillToolbarCustomButtonOptions` class diff --git a/doc/configurations/font_size.md b/doc/configurations/font_size.md index c73ddcb8..a4e25825 100644 --- a/doc/configurations/font_size.md +++ b/doc/configurations/font_size.md @@ -1,8 +1,12 @@ # Font Size -Within the editor toolbar, a drop-down with font-sizing capabilities is available. This can be enabled or disabled with `showFontSize`. +Within the editor toolbar, a drop-down with font-sizing capabilities is available. +This can be enabled or disabled +with `showFontSize`. -When enabled, the default font-size values can be modified via _optional_ `fontSizeValues`. `fontSizeValues` accepts a `Map` consisting of a `String` title for the font size and a `String` value for the font size. Example: +When enabled, the default font-size values can be modified via _optional_ `fontSizeValues`. +Accepts a `Map` consisting of a `String` title for the font size and a `String` value for the font size. +Example: ```dart fontSizeValues: const {'Small': '8', 'Medium': '24.5', 'Large': '46'} diff --git a/doc/configurations/localizations_setup.md b/doc/configurations/localizations_setup.md index cf446868..cf5c12f9 100644 --- a/doc/configurations/localizations_setup.md +++ b/doc/configurations/localizations_setup.md @@ -1,7 +1,9 @@ # Localizations Setup + in addition to the required delegates mentioned above in [Using custom app widget](./using_custom_app_widget.md) which are: + ```dart localizationsDelegates: const [ DefaultCupertinoLocalizations.delegate, @@ -9,9 +11,11 @@ localizationsDelegates: const [ DefaultWidgetsLocalizations.delegate, ], ``` + which are used by official Flutter widgets -The library also needs the +The library also needs the `FlutterQuillLocalizations.delegate` + ```dart // Required localizations delegates ... FlutterQuillLocalizations.delegate @@ -19,7 +23,10 @@ FlutterQuillLocalizations.delegate To offer the default localizations. -But **you don't have to** since we have wrapped the `QuillEditor` and `QuillToolbar` with `FlutterQuillLocalizationsWidget` which will check if it sets then it will go, if not, then it will be provided only for them, so it's not really required, but if you are overriding the `localizationsDelegates` you could also add the `FlutterQuillLocalizations.delegate` +But **you don't have to** since we have wrapped the `QuillEditor` and `QuillToolbar` +with `FlutterQuillLocalizationsWidget` which will check if it sets then it will go, if not, then it will be provided +only for them, so it's not really required, but if you are overriding the `localizationsDelegates` you could also add +the `FlutterQuillLocalizations.delegate` which won't change anything There are additional notes in the [Translation](../translation.md) section diff --git a/doc/configurations/using_custom_app_widget.md b/doc/configurations/using_custom_app_widget.md index d9457211..1b41bc2e 100644 --- a/doc/configurations/using_custom_app_widget.md +++ b/doc/configurations/using_custom_app_widget.md @@ -7,7 +7,7 @@ This project uses some adaptive widgets like `AdaptiveTextSelectionToolbar` whic 3. Default Widgets Localizations delegate You don't need to include those since they are defined by default - but if you are using a Custom app or you are overriding the `localizationsDelegates` in the App widget +but if you are using a Custom app or you are overriding the `localizationsDelegates` in the App widget then please make sure it includes those: ```dart @@ -18,7 +18,8 @@ localizationsDelegates: const [ ], ``` -You might need more depending on your use case, for example, if you are using custom localizations for your app, using a custom app widget like `FluentApp` from [FluentUI] +You might need more depending on your use case, for example, if you are using custom localizations for your app, using a +custom app widget like `FluentApp` from [FluentUI] which will also need ```dart @@ -29,7 +30,8 @@ localizationsDelegates: const [ ], ``` -Note: In the latest versions of `FluentApp` you no longer need to add the `localizationsDelegates` but this is just an example, for more [info](https://github.com/bdlukaa/fluent_ui/pull/946) +Note: In the latest versions of `FluentApp` you no longer need to add the `localizationsDelegates` but this is just an +example, for more [info](https://github.com/bdlukaa/fluent_ui/pull/946) There are additional notes on the [Localizations](./localizations_setup.md) page diff --git a/doc/custom_embed_blocks.md b/doc/custom_embed_blocks.md index a4f3b700..19f23ab5 100644 --- a/doc/custom_embed_blocks.md +++ b/doc/custom_embed_blocks.md @@ -1,12 +1,16 @@ # Custom Embed Blocks -Sometimes you want to add some custom content inside your text, custom widgets inside of them. An example is adding notes to the text, or anything custom that you want to add in your text editor. +Sometimes you want to add some custom content inside your text, custom widgets inside them. +An example is adding +notes to the text, or anything custom that you want to add in your text editor. -The only thing that you need is to add a `CustomBlockEmbed` and provide a builder for it to the `embedBuilders` parameter, to transform the data inside of the Custom Block into a widget! +The only thing that you need is to add a `CustomBlockEmbed` and provide a builder for it to the `embedBuilders` +parameter, to transform the data inside the Custom Block into a widget! Here is an example: -Starting with the `CustomBlockEmbed`, here we extend it and add the methods that are useful for the 'Note' widget, which will be the `Document`, used by the `flutter_quill` to render the rich text. +Starting with the `CustomBlockEmbed`, here we extend it and add the methods that are useful for the 'Note' widget, which +will be the `Document`, used by the `flutter_quill` to render the rich text. ```dart class NotesBlockEmbed extends CustomBlockEmbed { @@ -21,7 +25,8 @@ class NotesBlockEmbed extends CustomBlockEmbed { } ``` -After that, we need to map this "notes" type into a widget. In that case, I used a `ListTile` with a text to show the plain text resume of the note, and the `onTap` function to edit the note. +After that, we need to map this "notes" type into a widget. In that case, I used a `ListTile` with a text to show the +plain text resume of the note, and the `onTap` function to edit the note. Don't forget to add this method to the `QuillEditor` after that! ```dart @@ -64,7 +69,11 @@ class NotesEmbedBuilder extends EmbedBuilder { } ``` -And finally, we write the function to add/edit this note. The `showDialog` function shows the QuillEditor to edit the note after the user ends the edition, we check if the document has something, and if it has, we add or edit the `NotesBlockEmbed` inside of a `BlockEmbed.custom` (this is a little detail that will not work if you don't pass the `CustomBlockEmbed` inside of a `BlockEmbed.custom`). +And finally, we write the function to add/edit this note. +The `showDialog` function shows the QuillEditor to edit the +note after the user ends the edition, we check if the document has something, and if it has, we add or edit +the `NotesBlockEmbed` inside of a `BlockEmbed.custom` (this is a little detail that will not work if you don't pass +the `CustomBlockEmbed` inside of a `BlockEmbed.custom`). ```dart Future _addEditNote(BuildContext context, {Document? document}) async { @@ -116,11 +125,12 @@ Future _addEditNote(BuildContext context, {Document? document}) async { } ``` -And voila, we have a custom widget inside of the rich text editor! +And voilà, we have a custom widget inside the rich text editor!

1

-> 1. For more info and a video example, see the [PR of this feature](https://github.com/singerdmx/flutter-quill/pull/877) +> 1. For more info and a video example, see + the [PR of this feature](https://github.com/singerdmx/flutter-quill/pull/877) > 2. For more details, check out [this YouTube video](https://youtu.be/pI5p5j7cfHc) diff --git a/doc/custom_toolbar.md b/doc/custom_toolbar.md index fc661b6d..4e6650b7 100644 --- a/doc/custom_toolbar.md +++ b/doc/custom_toolbar.md @@ -1,6 +1,6 @@ # Custom Toolbar -If you want to use a custom toolbar but still want the support of this library +If you want to use a custom toolbar but still want the support of this library, You can use the `QuillBaseToolbar` which is the base for the `QuillToolbar` Example: @@ -112,4 +112,5 @@ QuillToolbar( ) ``` -if you want a more customized toolbar feel free to create your own and use the `controller` to interact with the editor. checkout the `QuillToolbar` and the buttons inside it to see an example of how that will work +if you want a more customized toolbar feel free to create your own and use the `controller` to interact with the editor. +checkout the `QuillToolbar` and the buttons inside it to see an example of how that will work diff --git a/doc/development_notes.md b/doc/development_notes.md index aaaba2be..dfdc6960 100644 --- a/doc/development_notes.md +++ b/doc/development_notes.md @@ -1,10 +1,22 @@ # Development notes -- When updating the translations or localizations in the app, please take a look at the [Translation](./translation.md) page as it has important notes in order to work, if you also add a feature that adds new localizations then you need to the instructions of it in order for the translations to take effect -- We use the same package version and `CHANGELOG.md` for all the packages, for more [details](https://github.com/singerdmx/flutter-quill/pull/1878), the process is automated. We have a script that will do the followings: - 1. Generate the `CHANGELOG.md` files by `CHANGELOG_JSON.json` (source of data) and then paste them into all the packages we have (overwrite), you don't need to - manually change/update any of the mentioned files above, once a new GitHub release published, the CI will take the release notes from the release, pass the info to the - script, the release notes can be auto-generated by Github using a button, a descirptive PRs title would help but you don't have to since we can change it at anytime. - 2. The script require the new version as an argument, you don't need to run the script manually, when a maintainer create a new tag and publish a new GitHub release, the publish workflow will extract the new version from the tag name, run the script (pass the extracted version as an argument), commit the changes and push them into the repository, the script will update the `version` property for all the packages so the `flutter pub publish` will use the new version for each package correctly. +- When updating the translations or localizations in the app, please take a look at the [Translation](./translation.md) + page as it has important notes to work. + If you also add a feature that adds new localizations, then you need it + to the instructions of it in order for the translations to take effect +- We use the same package version and `CHANGELOG.md` for all the packages, for + more [details](https://github.com/singerdmx/flutter-quill/pull/1878), the process is automated. We have a script that + will do the following: + 1. Generate the `CHANGELOG.md` files by `CHANGELOG_JSON.json` (source of data) and then paste them into all the + packages we have (overwrite), you don't need to + manually change/update any of the mentioned files above, once a new GitHub release published, the CI will take + the release notes from the release, pass the info to the + script, the release notes can be auto-generated by GitHub using a button, a descriptive PRs title would help but + you don't have to since we can change it at anytime. + 2. The script require the new version as an argument, you don't need to run the script manually, when a maintainer + create a new tag and publish a new GitHub release, the publish workflow will extract the new version from the tag + name, run the script (pass the extracted version as an argument), commit the changes and push them into the + repository, the script will update the `version` property for all the packages so the `flutter pub publish` will + use the new version for each package correctly. - the script will be used the CI and no need to run it manually \ No newline at end of file + the script will be used the CI and no need to run it manually \ No newline at end of file diff --git a/doc/todo.md b/doc/todo.md deleted file mode 100644 index 7617b022..00000000 --- a/doc/todo.md +++ /dev/null @@ -1,55 +0,0 @@ -# Todo - -This is a todo list page that added recently and will be updated soon. - -## Table of contents -- [Todo](#todo) - - [Table of contents](#table-of-contents) - - [Flutter Quill](#flutter-quill) - - [Features](#features) - - [Improvemenets](#improvemenets) - - [Bugs](#bugs) - - [Flutter Quill Extensions](#flutter-quill-extensions) - - [Features](#features-1) - - [Improvemenets](#improvemenets-1) - - [Bugs](#bugs-1) - -## Flutter Quill - -### Features - - - Add support for Text magnification feature, for more [info](https://github.com/singerdmx/flutter-quill/issues/1504) - - Provide a way to expose quills undo redo stacks, for more [info](https://github.com/singerdmx/flutter-quill/issues/1381) - - Add callback to the `QuillToolbarColorButton` for custom color picking logic - -### Improvemenets - - - Improve the Raw Quill Editor, for more [info](https://github.com/singerdmx/flutter-quill/issues/1509) - - Provide more support to all the platforms - - Extract the shared properties between `QuillRawEditorConfigurations` and `QuillEditorConfigurations` - - The todo in the this [commit](https://github.com/singerdmx/flutter-quill/commit/79597ea6425357795c0663588ac079665241f23a) needs to be checked - - use `maybeOf` and of instead `ofNotNull` in the providers to follow flutter offical convenstion, completly rework the providers and update the build context extensions - - Add line through to the text when the check point checked is true - - Change the color of the numbers and dots in ol/ul to match the ones in the item list - - Fix the bugs of the font family and font size - - Try to update Quill Html Converter - - When pasting a HTML text from cliboard by not using the context menu builder, the new logic won't work - - When selecting all text and paste HTML text, it will not replace the current text, instead it will add a text - - Add strike-through in checkbox text when the checkpoint is checked - - No more using of dynamic - - There is a bug here, the first character is not being formatted when choosing font family or font size and type in the editor - - Fix the toolbar and the toolbar buttons, rework some of them, for example missing tooltips - -### Bugs - -Empty for now. -Please go to the [issues](https://github.com/singerdmx/flutter-quill/issues) - - -## Flutter Quill Extensions - -### Features - -### Improvemenets - -### Bugs \ No newline at end of file diff --git a/doc/translation.md b/doc/translation.md index bbf92c64..0241a872 100644 --- a/doc/translation.md +++ b/doc/translation.md @@ -1,6 +1,8 @@ # Translation -The package offers translations for the quill toolbar and editor, it will follow the locale that is defined in your `WidgetsApp` for example `MaterialApp` which usually follows the system locally unless you set your own locale with: +The package offers translations for the quill toolbar and editor, it will follow the locale that is defined in +your `WidgetsApp` for example `MaterialApp` which usually follows the system locally unless you set your own locale +with: ```dart QuillToolbar.simple( @@ -38,16 +40,20 @@ Currently, translations are available for these 41 locales: The translation files are located in the [l10n](../lib/src/l10n/) folder. Feel free to contribute your own translations. -You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json) file, which is a generated file that tells you which keys with which locales haven't translated so you can find the missings easily. +You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json) file, which is a generated file that +tells you which keys with which locales haven't translated so you can find the missing easily.
Add new local -1. Create a new file in [l10n](../lib/src/l10n/) folder, with the following name`quill_${localName}.arb` for example `quill_de.arb` +1. Create a new file in [l10n](../lib/src/l10n/) folder, with the following name`quill_${localName}.arb` for + example `quill_de.arb` -2. Copy the [Arb Template](../lib/src/l10n/quill_en.arb) file and paste it into your new file, replace the values with your translations +2. Copy the [Arb Template](../lib/src/l10n/quill_en.arb) file and paste it into your new file, replace the values with + your translations -3. Update [Supported Locales](#supported-locales) section in this page to update the supported translations for both the number and the list +3. Update [Supported Locales](#supported-locales) section in this page to update the supported translations for both the + number and the list
@@ -58,13 +64,17 @@ You can take a look at the [untranslated.json](../lib/src/l10n/untranslated.json 2. Find the existing local, let's say you want to update the Korean translations, it will be `quill_ko.arb` -3. Use [untranslated.json](../lib/src/l10n/untranslated.json) as reference to find missings, update or add what you want to translate. +3. Use [untranslated.json](../lib/src/l10n/untranslated.json) as a reference to find missing, update or add what you + want + to translate.
-We usually avoid **updating existing value of a key in the template file without updating the key or creating a new one**, this will not update the [untranslated.json](../lib/src/l10n/untranslated.json) correctly and will make it harder for contributors to find missings or incomplete. - +> We usually avoid **updating the existing value of a key in the template file without updating the key or creating a new +one**. +> This will not update the [untranslated.json](../lib/src/l10n/untranslated.json) correctly and will make it harder +for contributors to find missing or incomplete. Once you finish, run the following script: @@ -80,9 +90,11 @@ dart fix --apply ./lib/src/l10n/generated dart format ./lib/src/l10n/generated ``` -The script above will generate Dart files from the Arb files in order to test the changes and take effect, otherwise you won't notice a difference. +The script above will generate Dart files from the Arb files to test the changes and take effect, otherwise you +won't notice a difference. -> If you added or removed translations in the template file, make sure to update `_expectedTranslationKeysLength` variable in [scripts/ensure_translations_correct.dart](../scripts/ensure_translations_correct.dart)
+> If you added or removed translations in the template file, make sure to update `_expectedTranslationKeysLength` +> variable in [scripts/ensure_translations_correct.dart](../scripts/ensure_translations_correct.dart)
> Otherwise you don't need to update it. Then open a pull request so everyone can benefit from your translations!