Skip to content

Latest commit

 

History

History
105 lines (72 loc) · 6.05 KB

README.md

File metadata and controls

105 lines (72 loc) · 6.05 KB
Raw

readability-reporter

This action reports readability scores and their changes for Markdown files in your pull requests, allowing you to quantify and track documentation improvements.

See example pull request comment

Readability after merging this PR: 19.53/100 (🟢 +0.32)

Path Readability
README.md 19.77 (🟢 +1.27)
View Detailed Metrics

🟢 - Shows an increase in readability 🔴 - Shows a decrease in readability

Path Readability FRE GF ARI CLI DCRS
README.md 19.77 42.18 17.28 30.2 11.38 7.57
  🟢 +1.27 🟢 +0.1 🟢 -0.14 🟢 -0.7 🔴 +0.23 🟢 -0.1

Averages:

  Readability FRE GF ARI CLI DCRS
Average 19.53 13.51 17.09 19.55 14.99 9.5
  🟢 +0.32 🟢 +0.02 🟢 -0.04 🟢 -0.18 🔴 +0.06 🟢 -0.03
View Metric Targets
Metric Range Ideal score
Flesch Reading Ease 100 (very easy read) to 0 (extremely difficult read) 60
Gunning Fog 6 (very easy read) to 17 (extremely difficult read) 8 or less
Auto. Read. Index 6 (very easy read) to 14 (extremely difficult read) 8 or less
Coleman Liau Index 6 (very easy read) to 17 (extremely difficult read) 8 or less
Dale-Chall Readability 4.9 (very easy read) to 9.9 (extremely difficult read) 6.9 or less

Readability scores

The text-readability library is used to determine the complexity and ease of reading for your documentation files. These scores can be used as a guide to help you understand how changes may impact the readability of your documentation.

Usage

Inputs

Name Necessity Description
github-token Required The GitHub token used to post the report comment to the pull request. The GitHub Actions token can be used with ${{ secrets.GITHUB_TOKEN }}.
glob Required The glob pattern to use for matching Markdown files you want analysed

Example workflow

name: Report readability

# This action only works on pull request events
on: pull_request

jobs:
    report-readability:
        name: Report readability
        runs-on: ubuntu-latest
        steps:
            - name: Checkout repo
              uses: actions/checkout@v2
            - uses: Rebilly/readability-reporter@v1
              with:
                  github-token: ${{ secrets.GITHUB_TOKEN }}
                  glob: '**/*.md'

Development

Commands

command description
test Run the unit tests
lint Run eslint on all files
format Run prettier on all files
build build the dist file. You are required to run this locally in order to build the dist before opening a PR.
run:local:report Run the action on two local folders, for testing and development. The first argument is the old ("base branch") folder and the sedcond argument is the new ("head branch") folder. For example yarn run:local:report ./test-data/old ./test-data/new
run:local:debugfile Show what the program parses from a single file, after stripping all non-wanted items from the file, and before rating the readability. For example yarn run:local:debugfile ./test-data/new/test-document.md

Testing

When developing the action, it can be useful to be able to run it locally rather than pushing a branch and running your development version on GitHub.

You can test the action locally by running the run:local:report command. This will report readability on two different folders, as if they were a pull request.

For example: yarn run:local:report ./test-data/old ./test-data/new