From aa38b325a13d432d12401f9eb51d592e30d53a80 Mon Sep 17 00:00:00 2001 From: CodeDoctorDE Date: Mon, 18 Nov 2024 16:16:16 +0100 Subject: [PATCH] Improve documentation of contributing --- CONTRIBUTING.md | 14 ++++++++++--- api/README.md | 53 +++++++++++++++++++++---------------------------- app/README.md | 28 ++++++++++---------------- 3 files changed, 45 insertions(+), 50 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 70732be81428..352faa27e7d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -34,10 +34,10 @@ Get started by running: ```bash cd docs pnpm install -pnpm start +pnpm dev ``` -All stable documentation can be found in the `versioned_docs` folder. +All content is written in the `docs/src/content/docs` folder. Please do not edit the localized files directly, but the directory `docs`, `downloads`, `community` and the `index.mdx` file. Fork the project and create a pull request to add your documentation to the `develop` branch. @@ -67,6 +67,14 @@ flutter pub get flutter run ``` -All subdirectories are documented in the `app/README.md` file. +All subdirectories are documented in the `README.md` file of the specific project `api` or `app`. Fork the project and create a pull request to add your code to the `develop` branch. + +### Getting started + +There are two different dart projects in this repository. + +In the `api` folder you will find general classes that can be used to interact with Butterfly files and general classes. Read more [here](https://github.com/LinwoodDev/Butterfly/blob/develop/api/README.md). + +The `app` folder contains the main app code. Read more [here](https://github.com/LinwoodDev/Butterfly/blob/develop/app/README.md). diff --git a/api/README.md b/api/README.md index 8b55e735b501..b225dd8ecc25 100644 --- a/api/README.md +++ b/api/README.md @@ -1,39 +1,32 @@ - +This library is meant to be used to interact with the Butterfly app or its files. It is written in Dart and can be used in any Dart project. -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. +## Project structure -## Features +The code for this library is stored in the `lib` directory. -TODO: List what your package can do. Maybe include images, gifs, or videos. +```markdown +lib/src +- converter +- helpers +- models +- protocol -## Getting started - -TODO: List prerequisites and provide or point to information on how to -start using the package. - -## Usage - -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. - -```dart -const like = 'sample'; +lib +- butterfly_api.dart +- butterfly_helpers.dart +- butterfly_models.dart +- butterfly_protocol.dart +- butterfly_text.dart ``` -## Additional information +* The `converter` directory stores all converters that converts file formats like xopp and older versions of Butterfly files to the new Butterfly file format. +* The `helpers` directory stores all helper functions (extensions) that simplify the usage of base classes, like strings and points. +* The `models` directory is the main part of this library. It stores all models that are used in the app. The base class of all Butterfly files is the `NoteData` class inside the `data.dart` file. +* The `protocol` directory stores all events and messages that are used in the app. The `event.dart` file stores all events that can be sent to the app. This can be used to interact with the collaboration feature of Butterfly. -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +For all directories, there is a specific file that exports all files in the directory. For example, the `butterfly_models.dart` file exports all files in the `models` directory. The special `butterfly_text.dart` file only exports the text models. +The `butterfly_api.dart` file exports all files in the `src` directory. diff --git a/app/README.md b/app/README.md index 3e5cc9ded485..a5b5cb7416e4 100644 --- a/app/README.md +++ b/app/README.md @@ -33,28 +33,22 @@ lib * The `actions` directory has all shortcuts that can be used in the app. * The `api` directory stores useful functions for the app. Some functions are separated between html (web) and io (native platforms). -* The `bloc` directory stores the save system of the app. In the `document_bloc.dart` file, you can see all handlers to the events that are defined in the `document_event.dart` file. The `document_state.dart` file stores all states that the app can have. -* The `cubits` directory stores small save systems that are not necessarily associated with the document. -* The `dialogs` directory stores all dialogs that can be opened in the app. For example the file system dialog or the open dialog. +* The `bloc` directory stores the save system of the app. In the `document_bloc.dart` file, you can see all handlers to the events that are defined in the `api/protocol/event.dart` file. The `document_state.dart` file stores all states that the app can have. +* The `cubits` directory stores small state systems that are not necessarily associated with the document. Here you also find the position and settings states. +* The `dialogs` directory stores all ui for the dialogs that can be opened in the app. For example the file system dialog or the open dialog. * The `embed` directory handles all events required for the embedding mode. -* The `handlers` directory stores all gesture handlers for the painters. -* The `helpers` directory stores all helper functions (extensions) that simplify the usage of classes. -* The `l10n` directory stores all the strings and translations that are used in the app. -* The `models` directory stores all the models that are used in the app. For example the `Document` model or the painters. +* The `handlers` directory stores all gesture handlers for the tools. Here it is defined that for example the `PenTool` creates a `PenElement` when the user starts drawing. +* The `helpers` directory stores all helper functions (extensions) that simplify the usage of base classes, like the `Rect` class. +* The `l10n` directory stores all the strings and translations that are used in the app. Please only edit the `app_en.arb` file, the other files gets updated by Crowdin. +* The `models` directory stores all app specific models that are not general to be added in the `api` directory. * The `services` directory defines all services that runs in the background while using the app. -* The `settings` directory stores all the settings pages that are used in the app. -* The `views` directory stores all the views that are used in the main page. For example the appbar, the toolbar or the main view. -* The `visualizer` directory stores all converters between the models and the ui. -* The `widgets` directory stores all general widget that is not specific to the app. For example the `OptionButton` widget. +* The `settings` directory stores all the settings pages ui that are used in the app. +* The `views` directory stores all the ui views that are used in the document page. For example the appbar, the toolbar or the main view. +* The `visualizer` directory are helper methods that stores all converters between the models and the ui. +* The `widgets` directory stores all general widget that can be reused inside the app. For example the context menu. ## Rebuilding assets -To rebuild the icon use: - -```bash -flutter pub run flutter_launcher_icons:main -f flutter_launcher_icons-production.yaml -``` - To rebuild the splash screen use: ```bash