diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml new file mode 100644 index 0000000..39b389a --- /dev/null +++ b/.github/workflows/documentation.yml @@ -0,0 +1,32 @@ +name: documentation +on: + workflow_dispatch: + pull_request: + branches: + - main + paths: + - 'docs/**' + - 'mkdocs.yml' +permissions: + contents: write +jobs: + deploy: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - name: Configure Git Credentials + run: | + git config user.name github-actions[bot] + git config user.email 41898282+github-actions[bot]@users.noreply.github.com + - uses: actions/setup-python@v5 + with: + python-version: 3.x + - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV + - uses: actions/cache@v4 + with: + key: mkdocs-material-${{ env.cache_id }} + path: .cache + restore-keys: | + mkdocs-material- + - run: pip install mkdocs-material + - run: mkdocs gh-deploy --force \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index fdd3fbc..dad328d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 1.0.0 + +- Documentation + README.md updates. + ## 0.0.2 - Add CodandoTV to the README.md description. diff --git a/README.md b/README.md index 4e5177b..d20e847 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/CodandoTV/eagle-eye/issues)[![Pub Version](https://img.shields.io/pub/v/eagle_eye?style=flat)](https://pub.dev/packages/eagle_eye) + # EagleEye **EagleEye** is a Dart CLI tool for **detecting architecture violations** in Dart projects. -> ⚠️ **Note:** This tool is under active development and **not yet production-ready**. +πŸ“š Check our documentation [here](https://codandotv.github.io/eagle-eye/). --- @@ -28,7 +30,7 @@ cd eagle_eye ⚠ We are working on a better way to distribute the library. ```yaml -dependencies: +dev_dependencies: eagle_eye: path: ../eagle_eye ``` diff --git a/docs/1-getting-started.md b/docs/1-getting-started.md new file mode 100644 index 0000000..2dab262 --- /dev/null +++ b/docs/1-getting-started.md @@ -0,0 +1,75 @@ +# Getting started πŸš€ + +## 1. Define rules + +- In the root level of you project, you need to create the file `eagle_eye_config.json` at the root level of your flutter/dart project. + +```json +[ + { + "filePattern": "*/data/model/*", + "noDependsEnabled": true + }, + { + "filePattern": "*viewmodel.dart", + "doNotWithPatterns": ["*_screen.dart"] + }, + { + "filePattern": "*/util/*_handler.dart", + "noDependsEnabled": true + } +] +``` + +In my first rule, I’m telling Eagle Eye that no file under the `data/model` path should have dependencies. + +The second rule states that my `ViewModels` must not depend on any screen-related files. + +I also have a third rule that enforces that our handler classes should not have any dependencies at all. + +## 2. Make sure you have a lint rule to avoid relative imports + +```yaml +# analysis_options.yaml + +analyzer: + errors: + avoid_relative_lib_imports: error +``` + +In this way, we are forcing the internal imports to have the app name: + +```dart +// BAD ❌ (relative import) +import '../utils/helper.dart'; +``` + +```dart +// GOOD βœ… (package import) +import 'package:my_app/utils/helper.dart'; +``` + +Ensure that this lint rule is enabled for EagleEye to function correctly. + +## 3. Add Eagle Eye dependency + +Add EagleEye to your project in `pubspec.yaml`: + +```yaml +# versions available, run `flutter pub outdated`. +dev_dependencies: + ... + eagle_eye: ^version +``` + +## 4. Run the CLI + +Now you can run the CLI, or integrate in your CI/CD pipeline as a required step. + +```shell +dart run eagle_eye:main +``` + +-- + +Any problems you are facing, any suggestions you want to add, please feel free to [reach us out](mailto:gabrielbronzattimoro.es@gmail.com). \ No newline at end of file diff --git a/docs/2-existing-rules.md b/docs/2-existing-rules.md new file mode 100644 index 0000000..6be51ed --- /dev/null +++ b/docs/2-existing-rules.md @@ -0,0 +1,44 @@ +# Existing rules πŸ“ + +We have several rules already defined in the plugin. You can create some rule too, take a look in our section about [contributions](./3-contributions.md). + +## DoNotWithRule + +The `DoNotWithRule` specifies that a set of file should not depend on certain files. For example: + +```json +// your-project-root/eagle_eye_config.json + { + "filePattern": "*viewmodel.dart", + "doNotWithPatterns": ["*_screen.dart"] + }, +``` + +In this case, all files that has the suffix `viewmodel.dart` should not depend on any file whose name includes '_screen.dart'. + +## JustWithRule + +The `JustWithRule` specifies that some files should depend on certain files. For example: + +```json +// your-project-root/eagle_eye_config.json + { + "filePattern": "*repository.dart", + "justWithPatterns": ["*_datasources.dart"] + }, +``` + +In this case, the our repositories should depend only on data sources. + +## NoDependencyRule + +The `NoDependencyRule` ensures that some files should remain free of any dependencies. For example: + +```json + { + "filePattern": "*util.dart", + "noDependsEnabled": true + }, +``` + +In this case, the all utils should be free of any internal dependencies. \ No newline at end of file diff --git a/docs/3-contributions.md b/docs/3-contributions.md new file mode 100644 index 0000000..80fa36c --- /dev/null +++ b/docs/3-contributions.md @@ -0,0 +1,9 @@ +# Contributions 🀝 + +We encourage contributions of all types! Whether it's reporting issues, suggesting new features, or submitting pull requests, you're welcome to help improve the plugin. + +- Check out the [issues](https://github.com/CodandoTV/eagle-eyeg/issues) page for ideas. + +- Feel free to submit [pull requests](https://github.com/CodandoTV/eagle-eye/pulls). + +πŸ€— Happy coding! \ No newline at end of file diff --git a/docs/4-tooling.md b/docs/4-tooling.md new file mode 100644 index 0000000..ec31bbd --- /dev/null +++ b/docs/4-tooling.md @@ -0,0 +1,31 @@ +# Tooling πŸ› οΈ + +## Mkdocs-material + +### How to run mkdocs locally? + +- Create your virtual env: + +```shell +python3 -m venv venv +``` + +- Open the new env: + +```shell +source venv/bin/activate +``` + +- Install mkdocs-material: + +```shell +pip install mkdocs-material +``` + +- Start the local server: + +```shell +mkdocs serve --watch . +``` + +Access your documentation at `http://127.0.0.1:8000/` \ No newline at end of file diff --git a/docs/img/logo.png b/docs/img/logo.png new file mode 100644 index 0000000..09ad25a Binary files /dev/null and b/docs/img/logo.png differ diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..4480dcb --- /dev/null +++ b/docs/index.md @@ -0,0 +1,20 @@ +[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/CodandoTV/eagle-eye/issues)[![Pub Version](https://img.shields.io/pub/v/eagle_eye?style=flat)](https://pub.dev/packages/eagle_eye) + + +# Welcome to the Eagle Eye documentation! πŸ‘‹ + +![Eagle Eye Logo](./img/logo.png) + +EagleEye is a Dart CLI tool for detecting architecture violations in Dart projects. + +Take a look at our [repository](https://github.com/CodandoTV/eagle-eye). + +## Summary + +### 1. [Getting started](1-getting-started.md) + +### 2. [Existing Rules](2-existing-rules.md) + +### 3. [Contributions](3-contributions.md) + +### 4. [Tooling](4-tooling.md) \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0578247 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,55 @@ +site_name: Eagle eye +repo_url: https://github.com/CodandoTV/eagle-eye +repo_name: EagleEye + +theme: + name: material + logo: img/logo.png + font: + text: Merriweather Sans + code: Red Hat Mono + icon: + repo: fontawesome/brands/github + features: + - navigation.footer + - content.code.annotations + - navigation.instant + - content.code.copy + palette: + #Β Dark Mode + - scheme: slate + toggle: + icon: material/weather-sunny + name: Dark mode + primary: deep purple + accent: light blue + + # Light Mode + - scheme: default + toggle: + icon: material/weather-night + name: Light mode + primary: deep purple + accent: blue + +markdown_extensions: + - smarty + - codehilite: + guess_lang: false + - footnotes + - meta + - toc: + permalink: true + - pymdownx.betterem: + smart_enable: all + - pymdownx.caret + - pymdownx.inlinehilite + - pymdownx.magiclink + - pymdownx.smartsymbols + - pymdownx.superfences + - pymdownx.emoji + - pymdownx.details + - pymdownx.tabbed: + alternate_style: true + - tables + - admonition \ No newline at end of file diff --git a/pubspec.yaml b/pubspec.yaml index 4b3b631..acbf7e0 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -2,7 +2,7 @@ name: eagle_eye description: "EagleEye is a Dart CLI tool provided by CodandoTV for detecting architecture violations in Dart projects." homepage: "https://github.com/CodandoTV/eagle-eye" -version: 0.0.2 +version: 1.0.0 environment: sdk: ^3.5.0