Update project readme

README.md

@@ -1,27 +1,37 @@
 ## Kataloger
 
-
 [![Latest version](https://img.shields.io/pypi/v/kataloger.svg?style=flat&label=Latest&color=%234B78E6&logo=&logoColor=white)](https://pypi.python.org/pypi/kataloger)
 [![Downloads](https://static.pepy.tech/badge/kataloger/month)](https://pepy.tech/project/kataloger)
 [![Tests](https://github.com/dzmpr/kataloger/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/dzmpr/kataloger/actions/workflows/run-tests.yml)
 [![Python version](https://img.shields.io/badge/python-3.11-blue.svg)](https://pypi.python.org/pypi/kataloger)
 
-Cataloger can help update your project dependencies with ease! All you need is point to `libs.versions.toml` file and supply it with repositories that you use in project.
+Kataloger can help update your project dependencies with ease! All you need is point to `libs.versions.toml` file and supply it with repositories that you use in project.
+
+### Features
+- Better than Android Studio built-in tool :)
+- Gradle-free
+- Can be used on CI
+- Flexible and open-source
 
 ### How to use?
-#### CLI mode
-Cataloger offers handy CLI mode which you can use locally or on CI:
+Kataloger offers handy CLI which you can use locally or on CI.
 
+You can pass path to version catalog using `-p` parameter and path to repositories that should be used to search for with `-rp` parameter:
 ```commandline
-pip install kataloger
-kataloger -p /ProjectDir/libs.versions.toml -rp /ProjectDir/default.repositories.toml
+kataloger -p ~/ProjectDir/libs.versions.toml -rp ~/ProjectDir/default.repositories.toml
 ```
+Repositories should be specified in separate `.toml` file separately for libraries and plugins. You can use [default](./src/kataloger/default.repositories.toml) repositories file as template.
 
-Or you can omit paths to version catalog and repositories if they are located in current working directory:
+If repositories not provided kataloger use [default](./src/kataloger/default.repositories.toml) set of repositories (Maven Central, Google Maven and Gradle Plugin Portal):
 
 ```commandline
-pip install kataloger
-cd /ProjectDir
+kataloger -p ~/ProjectDir/libs.versions.toml
+```
+
+Or you can omit paths to version catalog and repositories if they are located in current working directory. In this mode kataloger trying to find all catalogs (files with `.versions.toml` extension) and repositories in `default.repositories.toml` file in current directory:
+
+```commandline
+cd ~/ProjectDir
 kataloger
 ```
 
@@ -33,12 +43,30 @@ kataloger
 `-u` or `--suggest-unstable` — if specified suggest artifact update from stable version to unstable.  
 `-f` or `--fail-on-updates` — if specified return non-zero exit code when at least one update found. Can be useful on CI.
 
-#### Integrate cataloger to your python script
-Cataloger has convenient API (I did my best), so you can install it from pip and use in any script.
+### Installation
 
-### Roadmap
+Kataloger available in Python Package Index (PyPI). You can install kataloger using pip:
+```commandline
+pip install kataloger
+```
+
+### Use kataloger in python scripts
+Kataloger has convenient API (I did my best), so you can write custom logic on top. More info about it can be found [here](./src/kataloger/update_resolver).
+
+### License
 
-- [x] Support check multiple catalogs
-- [ ] Support all notations in version catalog
-- [ ] Support advanced update configuration
-- [ ] Support Python <3.11
+```text
+Copyright 2023 Dzmitry Pryskoka
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```

src/kataloger/update_resolver/README.md

@@ -0,0 +1,52 @@
+## Using kataloger in own scripts
+
+Kataloger can be used to implement your own update checking logic, but it still takes all work for gathering updates info.
+
+### Code structure
+
+Kataloger splits code responsibility for gathering updates info and code that searches for updates. Usually you don't need to modify code that fetches and parses maven metadata from the repository.
+But it's predictable that kataloger can't cover all you need in update resolution logic. 
+
+To address this problem [`UpdateResolver`](./base/update_resolver.py) were introduced. `UpdateResolver` is an abstract class, that should implement a single `resolve` method. 
+This method gets info about artifact and artifact metadata and should return [`UpdateResolution`](./base/update_resolution.py).
+`UpdateResolution` tells kataloger that there are no updates for artifact, update was found, or this resolver can't handle given artifact.
+So all you need to implement custom logic is to write the own `UpdateResolver` class.
+
+#### Example UpdateResolver
+
+Let's imagine we want to eagerly get artifact updates despite it stability status. `UpdateResolver` would look like this:
+
+```python
+class EagerlyUpdateResolver(UpdateResolver):
+
+    def resolve(
+        self,
+        artifact: Artifact,
+        repositories_metadata: list[MetadataRepositoryInfo],
+    ) -> tuple[UpdateResolution, Optional[ArtifactUpdate]]:
+        current_version = artifact.version
+        most_recently_updated_repo = max(repositories_metadata, key=lambda rm: rm.metadata.last_updated)
+        if most_recently_updated_repo.metadata.latest_version == current_version:
+            return UpdateResolution.UPDATE_FOUND, ArtifactUpdate(...)
+
+        return UpdateResolution.NO_UPDATES, None
+```
+
+Then we need to build an instance of [`CatalogUpdater`](../catalog_updater.py) with this resolver:
+
+```python
+catalog_updater = (CatalogUpdaterBuilder()
+                   .add_resolver(EagerlyUpdateResolver())
+                   .build())
+```
+
+### Special version notation
+
+By default, kataloger uses [`UniversalCatalogUpdater`](./universal/universal_update_resolver.py) that responsible for update resolution.
+This resolver tries to handle as much version notations as it can, such as [semantic versions](https://semver.org), semantic-like versions (with more or less digit parts) and google pre-release notations (`dev`, `alpha`, `beta`, etc.). 
+In case you just need to support special notation of artifact version, you can use `UniversalUpdateResolver` with own [`VersionFactory`](./universal/version_factory.py) and then there is no need to implement own `UpdateResolver`.
+`UniversalUpdateResolver` can use multiple version factories to instantiate comparable [`Version`](./universal/version.py) classes.
+
+### Contributing
+
+If you have a feature request or found a bug, feel free to open pull request or issue to make this tool better for everyone!