Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
85 changes: 19 additions & 66 deletions .github/workflows/update-best-of-list.yml
Original file line number Diff line number Diff line change
@@ -1,79 +1,32 @@
# Based on https://github.com/best-of-lists/best-of-update-action/blob/v0.8.5/workflows/update-best-of-list.yml
name: update-best-of-list

on:
workflow_dispatch:
inputs:
version:
description: "Version to use for this update"
required: false
schedule:
- cron: "0 18 * * 4" # Every thursday at 6pm
- cron: '32 6 * * 6' # At 06:32 every Saturday

env:
BRANCH_PREFIX: "update/"
DEFAULT_BRANCH: "main"
permissions:
contents: write
pull-requests: write

jobs:
update-best-of-list:
runs-on: ubuntu-latest
steps:
- if: ${{ github.event.inputs != null && github.event.inputs.version != null }}
name: set-version-from-input
run: echo "VERSION=${{ github.event.inputs.version }}" >> $GITHUB_ENV
- if: ${{ ! (env.VERSION != null && env.VERSION != '') }}
name: set-version-via-date
run: echo "VERSION=$(date '+%Y.%m.%d')" >> $GITHUB_ENV
- uses: actions/checkout@v4
- name: check-version-tag
shell: bash
run: |
git fetch --tags --force
git show-ref --tags --verify --quiet -- "refs/tags/${{ env.VERSION }}" && echo "VERSION=$(date '+%Y.%m.%d-%H.%M')" >> $GITHUB_ENV || exit 0
- name: create-update-branch
uses: peterjgrainger/action-create-branch@v3.0.0
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Download source
uses: actions/checkout@v6
with:
branch: "${{ env.BRANCH_PREFIX }}${{ env.VERSION }}"
- uses: actions/checkout@v3
branch: main
- name: Install best-of-generator
run: pip install git+https://github.com/ProperDocs/best-of-generator
- name: Generate best-of list
run: best-of generate projects.yaml --github-key=${{ secrets.GITHUB_TOKEN }}
- name: Create Pull Request
uses: peter-evans/create-pull-request@5f6978faf089d4d20b00c7766989d076bb2fc7f1 # v8.1.1
Comment on lines +24 to +25
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like making PRs only creates extra noise and work for us here, unless you setup some form of auto-merge after a time without review?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's just in case the system produces garbage/ empty results. Maybe it needs actual review. At least at first

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I just fear that this will create a lot of extra work for us in the future.
But for now is this probs the best to do I suppose.

Maybe have assignees configured tho, so that we are notified to check the PR?

with:
fetch-depth: 0
ref: ${{ env.BRANCH_PREFIX }}${{ env.VERSION }}
token: ${{ secrets.GITHUB_TOKEN }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: install best-of-generator
run: pip install git+https://github.com/mkdocs/best-of-generator
- name: update-best-of-list
run: best-of generate projects.yaml --github-key=${{ secrets.GITHUB_TOKEN }} --libraries-key=${{ secrets.LIBRARIES_KEY }}
- name: push-update
uses: stefanzweifel/git-auto-commit-action@v5
with:
branch: ${{ env.BRANCH_PREFIX }}${{ env.VERSION }}
commit_user_name: best-of update
commit_user_email: actions@github.com
commit_message: Update best-of list for version ${{ env.VERSION }}
tagging_message: ${{ env.VERSION }}
skip_dirty_check: true
commit_options: "--allow-empty"
- name: create-pull-request
shell: bash
run: |
# Stops script execution if a command has an error
set -e
curl -fsSL https://github.com/github/hub/raw/master/script/get | bash -s 2.14.2
bin/hub pull-request -b ${{ env.DEFAULT_BRANCH }} -h ${{ env.BRANCH_PREFIX }}${{ env.VERSION }} --no-edit -m "Best-of update: ${{ env.VERSION }}" -m "To finish this update: Select <code>Merge pull request</code> below and <code>Confirm merge</code>. Also, make sure to publish the created draft release in the [releases section](../releases) as well." || true
rm bin/hub
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# - name: create-release
# uses: softprops/action-gh-release@v2
# env:
# GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
# with:
# tag_name: ${{ env.VERSION }}
# name: "Update: ${{ env.VERSION }}"
# body_path: "latest-changes.md"
# draft: true
# prerelease: false
add-paths: README.md
commit-message: 'Update best-of list'
title: 'Update best-of list'
committer: 'github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>'
author: 'github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>'
branch: update
5 changes: 2 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,16 @@
</h1>

<p align="center">
<strong>:trophy: :books: A list of awesome <a href="https://github.com/mkdocs/mkdocs">MkDocs</a> projects and plugins.</strong>
<strong>:trophy: :books: A list of awesome themes and plugins that work with <a href="https://github.com/ProperDocs/properdocs">ProperDocs</a>.</strong>
</p>

<p align="center">
<a href="https://best-of.org" title="Best-of Badge"><img src="http://bit.ly/3o3EHNN"></a>
<a href="#Contents" title="Project Count"><img src="https://img.shields.io/badge/projects-300-blue.svg?color=5ac4bf"></a>
<a href="#Contribution" title="Contributions are welcome"><img src="https://img.shields.io/badge/contributions-welcome-green.svg"></a>
<a href="https://github.com/mkdocs/catalog/releases" title="Catalog Updates"><img src="https://img.shields.io/github/release-date/mkdocs/catalog?color=green&label=updated"></a>
</p>

This list contains 300 awesome open-source projects grouped into 17 categories. All projects are ranked by a project-quality score, which is calculated based on various metrics automatically collected from GitHub and different package managers. If you want to add or update projects, feel free to open an [issue](https://github.com/mkdocs/catalog/issues/new/choose), submit a [pull request](https://github.com/mkdocs/catalog/pulls), or directly edit the [projects.yaml](https://github.com/mkdocs/catalog/edit/main/projects.yaml). Contributions are very welcome!
This list contains 300 awesome open-source projects grouped into 17 categories. All projects are ranked by a project-quality score, which is calculated based on various metrics automatically collected from GitHub and different package managers. If you want to add or update projects, feel free to open an [issue](https://github.com/ProperDocs/catalog/issues/new/choose), submit a [pull request](https://github.com/ProperDocs/catalog/pulls), or directly edit the [projects.yaml](https://github.com/ProperDocs/catalog/edit/main/projects.yaml). Contributions are very welcome!

> 🧙‍♂️ Discover other [best-of lists](https://best-of.org) or [create your own](https://github.com/best-of-lists/best-of/blob/main/create-best-of-list.md).

Expand Down
68 changes: 29 additions & 39 deletions check_projects.py
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,6 @@
class Project(TypedDict, total=False):
name: Required[str]
category: Required[str]
labels: Required[Collection[str]]
properdocs_theme: str | Collection[str]
mkdocs_theme: str | Collection[str]
properdocs_plugin: str | Collection[str]
Expand All @@ -38,16 +37,17 @@ def _get_as_list(mapping: Project, key: EntrypointType) -> Collection[str]:
return names


_kinds_to_label: Mapping[Collection[EntrypointType], str] = {
("properdocs_plugin", "mkdocs_plugin"): "plugin",
("properdocs_theme", "mkdocs_theme"): "theme",
("markdown_extension",): "markdown",
}
_entrypoint_kinds: Collection[EntrypointType] = [
"properdocs_plugin",
"mkdocs_plugin",
"properdocs_theme",
"mkdocs_theme",
"markdown_extension",
]

config: Mapping[str, Any] = yaml.safe_load(Path("projects.yaml").read_text(encoding="utf-8"))

projects: Sequence[Project] = config["projects"]
all_labels: Collection[str] = dict.fromkeys(label["label"] for label in config["labels"])
all_categories: Collection[str] = dict.fromkeys(category["category"] for category in config["categories"])


Expand Down Expand Up @@ -127,7 +127,7 @@ def check_install_project(project: Project, install_names: Sequence[str], errors
pool = concurrent.futures.ThreadPoolExecutor(4)

# Tracks shadowing: projects earlier in the list take precedence.
available: dict[EntrypointType, dict[str, str]] = {k: {} for keys in _kinds_to_label for k in keys}
available: dict[EntrypointType, dict[str, str]] = {key: {} for key in _entrypoint_kinds}

futures: list[tuple[str, Future[list[str]]]] = []

Expand All @@ -143,39 +143,29 @@ def check_install_project(project: Project, install_names: Sequence[str], errors
errors.append("Project must have a 'category:'")
elif category not in all_categories:
errors.append(f"Unknown category: {category!r} - should be one of: {', '.join(all_categories)}")
labels = project.get("labels", ())
for label in labels:
if label not in all_labels:
errors.append(f"Unknown label: {label!r} - should be one of: {', '.join(all_labels)}")

for kinds, label in _kinds_to_label.items():
if label == "plugin" and "theme" in labels and "plugin" not in labels:
pass
elif (label in labels) != any(bool(project.get(kind)) for kind in kinds):
errors.append(f"'{label}' label should be present if and only if '{kinds}:' is present")

for kind in kinds:
items = _get_as_list(project, kind)

for item in items:
already_available: str | None = None
for subkind in (kind, cast("EntrypointType", kind.replace("mkdocs", "properdocs"))):
if already_available is None:
already_available = available[subkind].get(item)
if already_available is None and "plugin" in kind:
already_available = available[subkind].get(item.split("/")[-1])

if already_available:
if kind not in project.get("shadowed", ()):
errors.append(
f"{kind} '{item.split('/')[-1]}' is present in both project '{already_available}' and '{name}'.\n"
f"If that is expected, the later of the two projects will be ignored, "
f"and to indicate this, it should contain 'shadowed: [{kind}]'"
)
available[kind].setdefault(item, name)

for kind in _entrypoint_kinds:
items = _get_as_list(project, kind)

for item in items:
already_available: str | None = None
for subkind in (kind, cast("EntrypointType", kind.replace("mkdocs", "properdocs"))):
if already_available is None:
already_available = available[subkind].get(item)
if already_available is None and "plugin" in kind:
already_available = available[subkind].get(item.split("/")[-1])

if already_available:
if kind not in project.get("shadowed", ()):
errors.append(
f"{kind} '{item.split('/')[-1]}' is present in both project '{already_available}' and '{name}'.\n"
f"If that is expected, the later of the two projects will be ignored, "
f"and to indicate this, it should contain 'shadowed: [{kind}]'"
)
available[kind].setdefault(item, name)

install_name: str | None = None
if any(key in project for keys in _kinds_to_label for key in keys):
if any(key in project for key in _entrypoint_kinds):
if "pypi_id" in project:
install_name = project["pypi_id"].replace("_", "-")
if install_name != project["pypi_id"]:
Expand Down
3 changes: 1 addition & 2 deletions config/header.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,14 +5,13 @@
</h1>

<p align="center">
<strong>:trophy: :books: A list of awesome <a href="https://github.com/mkdocs/mkdocs">MkDocs</a> projects and plugins.</strong>
<strong>:trophy: :books: A list of awesome themes and plugins that work with <a href="https://github.com/ProperDocs/properdocs">ProperDocs</a>.</strong>
</p>

<p align="center">
<a href="https://best-of.org" title="Best-of Badge"><img src="http://bit.ly/3o3EHNN"></a>
<a href="#Contents" title="Project Count"><img src="https://img.shields.io/badge/projects-{project_count}-blue.svg?color=5ac4bf"></a>
<a href="#Contribution" title="Contributions are welcome"><img src="https://img.shields.io/badge/contributions-welcome-green.svg"></a>
<a href="https://github.com/mkdocs/catalog/releases" title="Catalog Updates"><img src="https://img.shields.io/github/release-date/mkdocs/catalog?color=green&label=updated"></a>
</p>

This list contains {project_count} awesome open-source projects grouped into {category_count} categories. All projects are ranked by a project-quality score, which is calculated based on various metrics automatically collected from GitHub and different package managers. If you want to add or update projects, feel free to open an [issue](https://github.com/ProperDocs/catalog/issues/new/choose), submit a [pull request](https://github.com/ProperDocs/catalog/pulls), or directly edit the [projects.yaml](https://github.com/ProperDocs/catalog/edit/main/projects.yaml). Contributions are very welcome!
Expand Down
1 change: 0 additions & 1 deletion history/2022-04-17_changes.md

This file was deleted.

Loading
Loading