{% set section = typer_help_chapters['Description'] %}
{{ section['intro'] }}

This is a small collection of tools to help automate some tasks related to Gentoo overlay maintenance.

It can:

* Generate a README like this.
* Look up a package in remotes and tell if a new version is available.
* Look up a package on [repology.org](https://repology.org) and show the newest known versions.

# Getting started

## Installation

Install the project from PyPI:

```console
$ pip install --user overlay-maintain-tools
```

Or from nitratesky overlay:

```console
$ eselect repository enable nitratesky && emerge -a1 app-portage/overlay-maintain-tools
```

## Sample usage

The overlay directory is at `/srv/overlay`. To generate a README with the badges, create a skeleton template
(like [the one in repo](https://raw.githubusercontent.com/VTimofeenko/overlay-maintain-tools/master/docs/templates/skeleton.jinja2)) and run:

```
$ overlay_maintain_tools --overlay-dir /srv/overlay mkreadme --skeleton-file /path/to/readme.template
```

To generate a report on packages versions in overlay, make sure that [`metadata.xml`](https://devmanual.gentoo.org/ebuild-writing/misc-files/metadata/index.html) file has remotes set and run:

```
$ overlay_maintain_tools --overlay-dir /srv/overlay check-remote-versions
```

To look up versions in repology, create a file with mapping between package atoms and project names in repology and specify it when running the script:

```
$ cat /srv/overlay/repology_cache
net-news/newsboat newsboat
$ overlay_maintain_tools --overlay-dir /srv/overlay check-repology --repology-cache-location /srv/overlay/repology_cache
```

# Details

{{ section['usage'] }}

{{ section['options']|replace("Options", "General Options", 1) }}

These options can be specified for any `COMMAND` except for  `create-config` which ignores these options.

{{ section['commands'] }}

# Commands
{% for s in ['mkreadme', 'check-remote-versions', 'check-repology'] %}
{% set section_id = 'overlay_maintain_tools ' + s %}
{% set section = typer_help_chapters["`" + section_id + "`"] %}
{{ section['intro'] }}

{{ section['usage'] }}

{{ section['options'] }}
{% endfor %}

# Contrib directory

There are shell completions for bash and zsh (generated through [typer](typer.tiangolo.com/)).