From 5a81d53f8687199c58486bb737563c1804c117ce Mon Sep 17 00:00:00 2001 From: Blarc Date: Thu, 27 Apr 2023 11:13:43 +0200 Subject: [PATCH] feat: add documentation --- README.md | 2 ++ docs/configuration.md | 69 ++++++++++++++++++++++++++++++++++++++++ docs/how-does-it-work.md | 23 ++++++++++++++ 3 files changed, 94 insertions(+) create mode 100644 docs/configuration.md create mode 100644 docs/how-does-it-work.md diff --git a/README.md b/README.md index b2d4bae..84af013 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ - [Compatibility](#compatibility) - [Install](#install) - [Installation from zip](#installation-from-zip) +- [How does it work](/docs/how-does-it-work.md) +- [Configuration](/docs/configuration.md) ## Description Gitlab Template Lint Plugin is a plugin for IntelliJ based IDEs/Android studio for linting diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 0000000..48062c2 --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,69 @@ +# Configuration + +The configuration tries to satisfy different users' needs and that's why it might be a bit more complicated. However, +for the basic usage, most configuration should be automatically resolved once you open a Gitlab Yaml file. + +## Gitlab API token + +The plugin needs a Gitlab API token to be able to make requests to the Gitlab Lint API. You can set the token in the +plugin settings for each Gitlab URL. Gitlab URLs are automatically resolved from the repositories URLs. + +**This should (in theory) be the only mandatory setting that you need to configure manually.** + +## Gitlab URL + +The plugin needs to know the Gitlab URL to be able to make requests to the Gitlab Lint API. The url is computed from +the repository URL. + +## Linting frequency + +The plugin needs to know when to lint the file. The default is to lint the file on every file save. + +## Self-signed certificate + +By default, the plugin does not allow self-signed certificates. You can enable it via this setting. + +## Force HTTPS + +By default, the plugin forces HTTPS. This means that if you have a Gitlab URL that starts with `http://`, the plugin +will try to use `https://` instead. You can disable this behavior via this setting. + +## Merged preview + +By default, the plugin shows a merged preview of the Gitlab Yaml file. You can disable this behavior via this setting. + +## Lint on selected file + +By default, the plugin lints the file whenever you switch tab in the editor. You can disable this behavior via this +setting to reduce the number of requests to the Gitlab Lint API. + +## Remote + +A repository can have multiple remotes. The plugin needs to know which remote to use when making requests to the Gitlab +Lint API. By default, this it is set to `origin`. + +## Fallback branch + +The plugin needs to know which branch to use as reference when making requests to the Gitlab Lint API. The current Git +branch is used by default. If the branch is not resolved correctly, the fallback branch is used. + +## Path globs + +The plugin needs to know which files to lint. By default, it lints all files that are recognized via the file type +mechanism. However, that might not always be specific enough. You can use path globs to specify which files to lint by +their path. + +## Remotes + +The plugin needs to know which Gitlab URL to use when making requests to the Gitlab Lint API. The plugin tries to +resolve the Gitlab URL from the remote URL. If it is not resolved correctly, you can set it manually. + +Because Gitlab URL is connected with the corresponding Gitlab API token, you must first create an entry in the Gitlab +URL Token table and then choose that Gitlab URL in the remotes table. This allows using the same Gitlab URL Token entry +for multiple remotes. + +### Gitlab project ID + +The plugin needs to know the Gitlab project ID to be able to make requests to the Gitlab Lint API. The plugin tries to +resolve the project ID, by searching for the project ID by its remote URL using the Gitlab project API, but it might +not always be resolved correctly. You can set the project ID manually for each repository in the remotes table. diff --git a/docs/how-does-it-work.md b/docs/how-does-it-work.md new file mode 100644 index 0000000..cb51a6d --- /dev/null +++ b/docs/how-does-it-work.md @@ -0,0 +1,23 @@ +# How does it work + +The plugin makes a request with your Gitlab Yaml file to the Gitlab Lint API, which returns a response whether the file +is valid or not. The plugin then parses the response and displays the errors in the editor. + +To make this happen, it does the following: + +1. Checks if the current file is a Gitlab Yaml file. +2. Tries to resolve the repository URL and Git branch for current file. +3. Parses Gitlab URL from the repository URL. +4. Checks if Gitlab API token exists for the Gitlab URL. + 1. If it doesn't exist: + 1. Saves the Gitlab URL to the Gitlab URL Token table in the plugin settings. + 2. Shows a notification to the user to set the Gitlab API token for the Gitlab URL. +5. Sends a request to the Gitlab Lint API with the current file content and the current branch as reference. + 1. If the reference branch does not exist on the remote and fallback branch is set, tries again with the fallback + branch. +6. Parses the response: + 1. displays the errors in the editor, if the file is not valid + 2. shows merged preview, if the file is valid and the preview is enabled + + +