Skip to content
Snippets Groups Projects
Unverified Commit c66f7bd4 authored by Przemek Rzad's avatar Przemek Rzad Committed by GitHub
Browse files

Improve the appearance of crates on `crates.io` (#5243)

## Context

Currently, many crates have no readme files, even though they are public
and available on crates.io.
Others have just a couple of words that does not look super presentable.

Even though probably nobody starts a journey with `polkadot-sdk` or its
documentation with a readme of a random low-level crate, I think it
would look more mature to have a little better readmes there.

So, in an attempt to improve [the
aesthetics](https://github.com/paritytech/eng-automation/issues/10) of
`polkadot-sdk`, I propose a set of consistent, branded, better-looking
readmes for all published crates.

## What's inside

- ~~New readme files for published crates.~~
- A python script to generate new readmes, for the crates that have
none.
  - It will skip crates that do have a readme, and private crates.
- Added a new image asset to the repo - logo with a background.
- The main readme of the repo uses a [nice
trick](https://github.com/paritytech/polkadot-sdk/blob/ce6938ae/README.md?plain=1#L4-L5)
to accompany both light and dark modes - but that doesn't work on
`crates.io` so a single logo with a background is needed.

## Example

### Current

![Screenshot 2024-08-04 at 16 13
36](https://github.com/user-attachments/assets/3ae0881d-0f40-4614-9d2c-3c95029f0820)

### Changed

![Screenshot 2024-08-04 at 16 12
28](https://github.com/user-attachments/assets/fa7eadc8-aec8-4f77-84d9-54d63ce189cd)
parent 559fa1db
Branches
No related merge requests found
Pipeline #492411 waiting for manual action with stages
in 1 hour
#!/usr/bin/env python3
"""
A script to generate READMEs for all public crates,
if they do not already have one.
It relies on functions from the `check-workspace.py` script.
The resulting README is based on a template defined below,
and includes the crate name, description, license,
and optionally - the SDK release version.
# Example
```sh
python3 -m pip install toml
.github/scripts/generate-readmes.py . --sdk-version 1.15.0
```
"""
import os
import toml
import importlib
import argparse
check_workspace = importlib.import_module("check-workspace")
README_TEMPLATE = """<div align="center">
<img src="https://raw.githubusercontent.com/paritytech/polkadot-sdk/master/docs/images/Polkadot_Logo_Horizontal_Pink_BlackOnWhite.png" alt="Polkadot logo" width="200">
# {name}
This crate is part of the [Polkadot SDK](https://github.com/paritytech/polkadot-sdk/).
</div>
## Description
{description}
## Additional Resources
In order to learn about Polkadot SDK, head over to the [Polkadot SDK Developer Documentation](https://paritytech.github.io/polkadot-sdk/master/polkadot_sdk_docs/index.html).
To learn about Polkadot, visit [polkadot.com](https://polkadot.com/).
## License
This crate is licensed with {license}.
"""
VERSION_TEMPLATE = """
## Version
This version of `{name}` is associated with Polkadot {sdk_version} release.
"""
def generate_readme(member, *, workspace_dir, workspace_license, sdk_version):
print(f"Loading manifest for: {member}")
manifest = toml.load(os.path.join(workspace_dir, member, "Cargo.toml"))
if manifest["package"].get("publish", True) == False:
print(f"⏩ Skipping un-published crate: {member}")
return
if os.path.exists(os.path.join(workspace_dir, member, "README.md")):
print(f"⏩ Skipping crate with an existing readme: {member}")
return
print(f"📝 Generating README for: {member}")
license = manifest["package"]["license"]
if isinstance(license, dict):
if not license.get("workspace", False):
print(
f"❌ License for {member} is unexpectedly declared as workspace=false."
)
# Skipping this crate as it is not clear what license it should use.
return
license = workspace_license
name = manifest["package"]["name"]
description = manifest["package"]["description"]
description = description + "." if not description.endswith(".") else description
filled_readme = README_TEMPLATE.format(
name=name, description=description, license=license
)
if sdk_version:
filled_readme += VERSION_TEMPLATE.format(name=name, sdk_version=sdk_version)
with open(os.path.join(workspace_dir, member, "README.md"), "w") as new_readme:
new_readme.write(filled_readme)
def parse_args():
parser = argparse.ArgumentParser(
description="Generate readmes for published crates."
)
parser.add_argument(
"workspace_dir",
help="The directory to check",
metavar="workspace_dir",
type=str,
nargs=1,
)
parser.add_argument(
"--sdk-version",
help="Optional SDK release version",
metavar="sdk_version",
type=str,
nargs=1,
required=False,
)
args = parser.parse_args()
return (args.workspace_dir[0], args.sdk_version[0] if args.sdk_version else None)
def main():
(workspace_dir, sdk_version) = parse_args()
root_manifest = toml.load(os.path.join(workspace_dir, "Cargo.toml"))
workspace_license = root_manifest["workspace"]["package"]["license"]
members = check_workspace.get_members(workspace_dir, [])
for member in members:
generate_readme(
member,
workspace_dir=workspace_dir,
workspace_license=workspace_license,
sdk_version=sdk_version,
)
if __name__ == "__main__":
main()
docs/images/Polkadot_Logo_Horizontal_Pink_BlackOnWhite.png

202 KiB

docs/images/Polkadot_Logo_Horizontal_Pink_WhiteOnBlack.png

200 KiB

0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment