Skip to content

Commit

Permalink
readme polished, logo added (#37)
Browse files Browse the repository at this point in the history 
Readme polished

### What's done:
1) readme polished
2) new logo
  • Loading branch information
@yegor256
yegor256 authored Jul 8, 2020
1 parent d3b1943 commit 0ed76ad
Show file tree
Hide file tree
Showing 5 changed files with 170 additions and 108 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,4 @@ build
/.idea
*.iml
out
.DS_Store
233 changes: 125 additions & 108 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,148 +1,165 @@
![diktat logo](diktat_small.jpg)

<img src="/logo.svg" width="64px"/>

![Build and test](https://github.com/cqfn/diKTat/workflows/Build%20and%20test/badge.svg)
![deteKT static analysis](https://github.com/cqfn/diKTat/workflows/Run%20deteKT/badge.svg)
![Releases](https://img.shields.io/github/v/release/cqfn/diKTat)
![License](https://img.shields.io/github/license/cqfn/diKtat)
[![Releases](https://img.shields.io/github/v/release/cqfn/diKTat)](https://github.com/cqfn/diKTat/releases)
[![License](https://img.shields.io/github/license/cqfn/diKtat)](https://github.com/cqfn/diKTat/blob/master/LICENSE)

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2Fcqfn%2FdiKTat.svg?type=shield)](https://app.fossa.com/projects/git%2Bgithub.com%2Fcqfn%2FdiKTat?ref=badge_shield)
[![Awesome Kotlin Badge](https://kotlin.link/awesome-kotlin.svg)](https://github.com/KotlinBy/awesome-kotlin)
[![ktlint](https://img.shields.io/badge/code%20style-%E2%9D%A4-FF4081.svg)](https://ktlint.github.io/)
[![Chat on Telegram](https://img.shields.io/badge/Chat%20on-Telegram-brightgreen.svg)](https://t.me/joinchat/AAAAAFDg-ipuZFGyBGPPeg)
[![Hits-of-Code](https://hitsofcode.com/github/cqfn/diktat)](https://hitsofcode.com/view/github/cqfn/diktat)
[![codecov](https://codecov.io/gh/cqfn/diKTat/branch/master/graph/badge.svg)](https://codecov.io/gh/cqfn/diKTat)

## diKTat project
### What is diKTat
diKTat ([github](https://github.com/cqfn/diKTat)) - is a rule set of Kotlin code style rules that are using [KTlint](https://ktlint.github.io/) framework under the hood.
In this project we are trying to define Kotlin code style rules and implement them as visitors for AST tree provided by Ktlint.
It will detect (check) and fix code style issues based on [diKTat Kotlin codestyle](https://github.com/cqfn/diKTat/wiki/diKTat-codestyle-guide).
[![Chat on Telegram](https://img.shields.io/badge/Chat%20on-Telegram-brightgreen.svg)](https://t.me/joinchat/AAAAAFDg-ipuZFGyBGPPeg)

It is a collection of [Kotlin](https://kotlinlang.org/) code style rules implemented
as AST visitors on top of [KTlint](https://ktlint.github.io/).
The full list of rules is [here](https://github.com/cqfn/diKTat/wiki/diKTat-codestyle-guide).

## Usage
diKTat uses KTlint framework so see it's [usage first](https://ktlint.github.io/)
First, [install KTlint](https://ktlint.github.io/).
Then, load diKTat:

### How to: run default configuration of diKTat as CLI application
load KTlint:
```shell script
curl -sSLO https://github.com/pinterest/ktlint/releases/download/0.37.2/ktlint && chmod a+x ktlint`
```bash
$ curl -sSLO https://central.artipie.com/akuleshov7/diktat/org/cqfn/diktat/diktat-rules/0.0.1/diktat-rules-0.0.1-jar-with-dependencies.jar
```
you can also download ktlint manually from [ktlint project repo](https://github.com/pinterest/ktlint/releases)
another option for MacOS is `brew install ktlint`

load diKTat:
```shell script
curl -sSLO https://central.artipie.com/akuleshov7/diktat/org/cqfn/diktat/diktat-rules/0.0.1/diktat-rules-0.0.1-jar-with-dependencies.jar
```
Finally, run KTlint with diKTat injected to check your `*.kt` files in `src/test`:

run KTlint with diKTat injected:
```shell script
./ktlint -R diktat-rules-0.0.1-jar-with-dependencies.jar "src/test/**/*.kt"
```bash
$ ./ktlint -R diktat-rules-0.0.1-jar-with-dependencies.jar "src/test/**/*.kt"
```

this will run the default configuration of diKTat in check mode. To start autofixing use `-F` option. \
To see any reference related to ktlint - see: [KTlint](https://ktlint.github.io/) or use:
To autofix all violations use `-F` option.

If in trouble, try this:

`./ktlint -help`

### How to: run default configuration of diKTat with maven plugin
Please note, that currently diKTat releases are hosted on the [Artipie](https://www.artipie.com/), so you need to add lines below to your pom.xml file:
## Maven Plugin

Currently diKTat releases are hosted on the
[Artipie](https://www.artipie.com/),
so you need to add lines below to your `pom.xml` file:

```xml
<distributionManagement>
<repository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</repository>
<snapshotRepository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</snapshotRepository>
</distributionManagement>
<repositories>
<repository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</repository>
</repositories>
<project>
[...]
<distributionManagement>
<repository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</repository>
<snapshotRepository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</snapshotRepository>
</distributionManagement>
<repositories>
<repository>
<id>artipie</id>
<url>https://central.artipie.com/akuleshov7/diktat</url>
</repository>
</repositories>
</project>
```

add this snippet to your pom.xml `<build>-<plugins>` section:
Add this snippet to your pom.xml:

```xml
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
<executions>
<execution>
<id>ktlint</id>
<phase>verify</phase>
<configuration>
<target name="ktlint">
<java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true"
classpathref="maven.plugin.classpath" classname="com.pinterest.ktlint.Main">
<arg value="src/**/*.kt"/>
</java>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.pinterest</groupId>
<artifactId>ktlint</artifactId>
<version>0.37.2</version>
</dependency>
<dependency>
<groupId>org.cqfn.diktat</groupId>
<artifactId>diktat-rules</artifactId>
<version>0.0.1-SNAPSHOT</version>
</dependency>
</dependencies>
</plugin>
<project>
[...]
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-antrun-plugin</artifactId>
<version>1.8</version>
<executions>
<execution>
<id>ktlint</id>
<phase>verify</phase>
<configuration>
<target name="ktlint">
<java taskname="ktlint" dir="${basedir}" fork="true" failonerror="true"
classpathref="maven.plugin.classpath" classname="com.pinterest.ktlint.Main">
<arg value="src/**/*.kt"/>
</java>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
<dependencies>
<dependency>
<groupId>com.pinterest</groupId>
<artifactId>ktlint</artifactId>
<version>0.37.2</version>
</dependency>
<dependency>
<groupId>org.cqfn.diktat</groupId>
<artifactId>diktat-rules</artifactId>
<version>0.0.1-SNAPSHOT</version> <!-- replace it with our current version -->
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>
```

in case you want to add autofixer with diktat ruleset just extend the snippet above with: `<arg value="-F"/>`
In case you want to add autofixer with diKTat ruleset just extend
the snippet above with `<arg value="-F"/>`.

## Customizations via `rules-config.json`

In KTlint, rules can be configured via `.editorconfig`, but
this does not give a chance to customize or enable/disable
each and every rule independently.
That is why we have supported `rules-config.json` that can be easily
changed and help in customization of your own rule set.
It has simple fields:
`name` — name of the rule,
`enabled` (true/false) — to enable or disable that rule, and
`configuration` — a simple map of some extra unique configurations for the rule.
For example:

### How to: make deep customization of diKTat (rules-config.json)
In ktlint rules can be configured via .editorconfig, but this does not give a chance to customize or enable/disable each and every rule independently.
That is why we have supported `rules-config.json` that can be easily changed and help in customization of your own rule set.
It has simple fields: "name" - name of the rule, "enabled" (true/false) to enable or disable that rule and "configuration" - a simple map of some extra unique configurations for the rule, for example:
```json
"configuration": {
"isCopyrightMandatory": true,
"copyrightText": "Copyright (c) Huawei Technologies Co., Ltd. 2012-2020. All rights reserved."
}
"configuration": {
"isCopyrightMandatory": true,
"copyrightText": "Copyright (c) Jeff Lebowski, 2012-2020. All rights reserved."
}
```

To see all list of available configurations go to our wiki: [Available inspections](info/available-rules.md)
## How to contribute?

## Development
### Main components
Main components are:
1) diktat-ruleset - number of rules that are supported by diKTat
2) diktat-test-framework - functional/unit test framework that can be used for running your code fixer on the initial code and compare it with the expected result
3) also see our demo: diktat-demo in a separate repository
1) diktat-ruleset — number of rules that are supported by diKTat;
2) diktat-test-framework — functional/unit test framework that can be used for running your code fixer on the initial code and compare it with the expected result;
3) also see our demo: diktat-demo in a separate repository.

### How to: build the project
### What was hacked and changed in KTlint and why do we temporary need a fork of it?
Mainly we wanted to create a common configurable mechanism that will give us a chance to enable/disable and customize all rules.
Mainly we wanted to create a common configurable mechanism that
will give us a chance to enable/disable and customize all rules.
That's why we added logic for:
1) Parsing .json file with configurations of rules and passing it to visitors
2) Passing information about properties to visitors. This information is very useful, when you are trying to get, for example, a filename of file where the code is stored.
3) We added a bunch of visitors that will extended KTlint functionaliity
1) Parsing .json file with configurations of rules and passing it to visitors;
2) Passing information about properties to visitors. This information is very useful, when you are trying to get, for example, a filename of file where the code is stored;
3) We added a bunch of visitors that will extended KTlint functionaliity.

Download:
```shell script
git clone https://github.com/akuleshov7/diKTat.git

```bash
$ git clone https://github.com/akuleshov7/diKTat.git
```

We are using maven as we tired of Gradle:
```shell script
mvn clean install
We are using Maven as we are tired of Gradle:

```bash
$ mvn clean install
```

This will also install git hooks into your local .git directory. The hooks will restrict commit messages and branch naming.
This will also install git hooks into your local `.git` directory. The hooks
will restrict commit messages and branch naming.

### Contribution policy
Please follow our [contributing policy](info/CONTRIBUTING.md)
Binary file removed diktat_small.jpg
View file
Binary file not shown.
Binary file added logo-1024.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading

0 comments on commit 0ed76ad

Please sign in to comment.