best-of 0.5.0

Generates a ranked list of awesome libraries and tools.

Best-of Generator

🏆  Generates a ranked markdown list of awesome libraries and tools.

Getting Started • Documentation • Support • Report a Bug • Contribution • Changelog

The best-of-generator is a CLI tool to generate a markdown page of ranked open-source projects based on a list of projects defined in a yaml file. It is integrated with different package managers - such as PyPI, NPM, Conda, and DockerHub - to automatically collect a variety of project metadata and calculate project-quality scores. It also comes with a Github Action workflow for a fully automized update process.

Highlights

• 📇  Generates a beatiful markdown page from a yaml list.
• 🔌  Integrates various package managers (npm, pypi, conda ...).
• 🔄  Github Action workflow for automated weekly updates.
• 📈  Identify trending projects based on collected metrics.

Getting Started

Run via Github Action

Run via CLI

Support & Feedback

This project is maintained by Benjamin Räthlein, Lukas Masuch, and Jan Kalkan. Please understand that we won't be able to provide individual support via email. We also believe that help is much more valuable if it's shared publicly so that more people can benefit from it.

Type	Channel
🚨  Bug Reports
🎁  Feature Requests
👩‍💻  Usage Questions
📢  Announcements
❓  Other Requests

Documentation

TODO

projects.yaml

TODO

Project Properties

TODO

Property	Description
name	Name of the project.
github_id	Github ID of the project based on user or organization and the repository name (e.g. best-of-lists/best-of-generator).
category	Category that this project is most related to. You can find all available category IDs in the projects.yaml file. The project will be sorted into the Others category if no category is provided.
Optional Properties:
license	License of the project. If set, license information from Github or package managers will be overwritten.
labels	List of labels that this project is related to. You can find all available label IDs in the projects.yaml file.
description	Short description of the project. If set, the description from Github or package managers will be overwritten.
homepage	Hompage URL of the project. Only use this property if the project homepage is different from the Github URL.
docs_url	Documentation URL of the project. Only use this property if the project documentation site is different from the Github URL.
Supported Package Managers:
pypi_id	Project ID on the python package index (pypi.org).
conda_id	Project ID on the conda package manager (anaconda.org). If the main package is provided on a different channel, prefix the ID with the given channel: e.g. conda-forge/tensorflow
npm_id	Project ID on the Node package manager (npmjs.com).
dockerhub_id	Project ID on the Dockerhub container registry (hub.docker.com).

Categories

TODO

Labels

TODO

Configuration

Config	Description	Default
project_inactive_months	Number of month without activity until a project is marked as inactive.	6
project_dead_months	Number of month without activity until a project is marked as dead.	12
project_new_months	Number of month since creation to mark a project as newcomer.	6
min_projectrank	Project will be hidden if it has a smaller projectrank (quality score).	10
min_stars	Project will be hidden if it has a less stars on GitHub.	100
require_license	If True, all projects without a detected license will be hidden.	True
require_github	If True, all projects without a github_id will be hidden.	False
markdown_output_file	The markdown output file.	./README.md
projects_history_folder	The folder used for storing history files (csv files with project metadata). If null, no history files will be created.	./history
generate_install_hints	If False, the install hint code block for the package managers will not be shown.	True
generate_toc	If True, generate a table of content with all categories.	True
generate_legend	If True, generate a legend containing explanations for the used emojis.	True
sort_by	The project property used to sort the projects within a category.	projectrank
max_trending_projects	The number of trending projects to show for trending up as well as down.	5
hide_empty_categories	If True, empty categories will not be shown.	False
hide_project_license	If True, the project license badge will not be shown.	False
show_labels_in_legend	If True, image labels will be listed in the legend (explanation) if they also have a description.	True
allowed_licenses	List of allowed licenses (spdx format). A project with a different license will be hidden. Use ["all"] to allow all licenses.	selection of common open-source licenses

Trending Projects

TODO

Project Quality Score

TODO

Generator CLI

TODO

Known Issues

The generated README file is not displayed completely (click to expand...)

Github only renders the first 512 kb of the main README.md file and will cut of the rendered version as soon as it has processed the first 512 kb of the raw markdown content. The rendering is only cut off when viewing the readme on the main repo page, if you directly select the README.md file, it will render in its entirety. To mitigate this issue, we optimized the markdown generation to require the minimum amount of characters. However, if you have a very large list of projects (more than 800), you might reach the 512 kb limit (check the file size of the generated README.md file). In this case, we suggest to extract some of the categories or projects into smaller best-of lists.

Contribution

• Pull requests are encouraged and always welcome. Read our contribution guidelines and check out help-wanted issues.
• Submit Github issues for any feature request and enhancement, bugs, or documentation problems.
• By participating in this project, you agree to abide by its Code of Conduct.
• The development section below contains information on how to build and test the project after you have implemented some changes.

Development

Requirements: Docker and Act are required to be installed on your machine to execute the containerized build process.

To simplify the process of building this project from scratch, we provide build-scripts - based on universal-build - that run all necessary steps (build, check, test, and release) within a containerized environment. To build and test your changes, execute the following command in the project root folder:

act -b -j build

Refer to our contribution guides for more detailed information on our build scripts and development process.

---

Licensed MIT. Created and maintained with ❤️  by developers from Berlin.