bryant1410/readmesfix

Because I'm tired of running into broken READMEs!

Fix GitHub's Markdown headings

Because I'm tired of running into broken READMEs!

GitHub changed the way ATX headers are parsed in Markdown files. This caused many repos' READMEs to have their headings suddenly broken, and albeit time have passed, many are still broken.

vmarkovtsev created a dataset (CC BY-NC 4.0) containing the repos with more than 50 stars that contain READMEs broken in this way. So I created this script to iterate through the list and create a PR to fix each of them.

Set up

Caution: this is an automated script to create Pull Requests. Please be cautious to avoid creating spam with it.

The script works on Python 3.6+. To install its dependencies:

pip install -r requirements.txt

To run it, you first need to configure a Personal Access Token with repo:public_repo scope to be able to fork projects and to create pull requests. Then:

export GITHUB_ACCESS_TOKEN=<YOUR ACCESS TOKEN>
./readmesfix.py

It will start processing each repo in the file (one by line) by cloning it, finding its Markdown files, checking if they should be fixed, forking them and creating a pull request. Take into account GitHub API rate limiting, so avoid overwhelming it by making the script much faster.

To select a different dataset than top_broken.tsv:

./readmesfix.py --dataset dataset_file

Testing

To test this script:

python -m unittest discover

readmesfix's Issues

Keep files' line-endings

Fix a repo in a non-default branch

As asked in blabla1337/skf-flask#119. Then, process it.

Separate fixing files from source and auto PR

Thanks for this!

I would love to be able to run this script over all markdown files in my project, but I'd like to just pass in a directory, or a list of files, and not have a PR auto-generated.

code blocks in readme

This appears to false positive on code examples inside the README.md file. perhaps ignore headers followed by the word include? "#include "

bryant1410/arduino-mqtt@a650250

Ignore # lines found in ``` sections

I received a PR that incorrectly updates a #pragma line in a code snippet in a ``` section.

Fix repos' Markdown files

The repos in the list should have their Markdown files fixed.

Detect Markdown code with <pre> and/or <code>

As in geekammo/MicroView-Arduino-Library#31

See why docker-exec/dexec failed

docker-exec/dexec#66 had some false positives.

Hello world

Thank you and this project may need a How-To-Do

Hi bryant1410, Thank you for pull requests to fix my projects Markdown files.

I think this project can add a How-To-Do, so more user can use it, and save the users time also. for example:

1. set {ENV_VAR_NAME} at first

2. run readmesfix.py and what params.

3. How to new a pull request auto.

4. ...

and more.

Thank you.

See why bulik/ldsc failed

bulik/ldsc#80 had several false negatives.

Script also "fixes" commented out headers

Submitting on technicalities only.

Your script will also fix non-visible, commented-out headers (see here).

This might still be desired just to catch all possible mistakes, but your pull request didn't have any visible changes to my users.

Avoid navigating through "Pods" folders

As noted in andreamazz/AMTagListView#63

Run the project in repos' wikis