# DAS Readability
**Checks the readability of markdown files in a directory and its subdirectories.**
---
## Usage
```bash
readability ./docs
```
CLI Arguments:
- `--directory` (required) argument is required and specifies the directory to search for .md files.
- `--show-all` argument can be used to show scores for all files, even if they meet the desired readability levels.
- `--ignore` argument can be used to specify directories to ignore.
- `--verbose` argument can be used to print the content that is being evaluated.
- `--smog` argument can be used to specify the SMOG Index threshold.
- `--flesch` argument can be used to specify the Flesch Reading Ease threshold.
## Why
w
The reasoning for creating this script is to ensure that the documentation and
communication materials are easily understood by the intended audience.
Intended audience for most of DAS documentation is IT Professionals, so the readability
should be at the level of an undergraduate student or higher.
## What
It uses the textstat library to calculate the SMOG Index and Flesch Reading Ease score of
the textual content of `.md` documents.
The SMOG Index is chosen due to its general application in the healthcare industry.
The Flesch Reading Ease score is chosen due to its wide and storied use.
The script outputs a table of the results, including the file name, SMOG Index, and
Flesch Reading Ease score.
## Future
Unfortunately, the textstat library does not report on the words or structures that are
causing the readability issues. This would be a useful feature to add in the future.
The scripts also only evaluates the total complexity of a document.
Meaning that half of the document might actually be quite complex
while the other half is very simple, evening out the score.
**Contributions are very welcome.**
Raw data
{
"_id": null,
"home_page": "https://github.com/innersource-nn/das-readability",
"name": "das-readability",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.9.7",
"maintainer_email": null,
"keywords": "readability, markdown, textstat, cli, smog, reading, ease, flesch",
"author": "lzvb",
"author_email": "lzvb@novonordisk.com",
"download_url": "https://files.pythonhosted.org/packages/5e/33/975666d83337d0d73fd239a83cbbfb5854b8ebab3d0602f88e7e25fef5d4/das_readability-2.0.0.tar.gz",
"platform": null,
"description": "# DAS Readability\n\n**Checks the readability of markdown files in a directory and its subdirectories.**\n\n---\n\n## Usage\n\n```bash\nreadability ./docs\n```\n\nCLI Arguments:\n\n- `--directory` (required) argument is required and specifies the directory to search for .md files.\n- `--show-all` argument can be used to show scores for all files, even if they meet the desired readability levels.\n- `--ignore` argument can be used to specify directories to ignore.\n- `--verbose` argument can be used to print the content that is being evaluated.\n- `--smog` argument can be used to specify the SMOG Index threshold.\n- `--flesch` argument can be used to specify the Flesch Reading Ease threshold.\n\n## Why\nw\nThe reasoning for creating this script is to ensure that the documentation and\ncommunication materials are easily understood by the intended audience.\nIntended audience for most of DAS documentation is IT Professionals, so the readability\nshould be at the level of an undergraduate student or higher.\n\n## What\n\nIt uses the textstat library to calculate the SMOG Index and Flesch Reading Ease score of\nthe textual content of `.md` documents.\n \nThe SMOG Index is chosen due to its general application in the healthcare industry.\nThe Flesch Reading Ease score is chosen due to its wide and storied use.\n\nThe script outputs a table of the results, including the file name, SMOG Index, and\nFlesch Reading Ease score.\n\n## Future\n\nUnfortunately, the textstat library does not report on the words or structures that are\ncausing the readability issues. This would be a useful feature to add in the future.\n\nThe scripts also only evaluates the total complexity of a document.\nMeaning that half of the document might actually be quite complex\nwhile the other half is very simple, evening out the score.\n\n**Contributions are very welcome.**\n",
"bugtrack_url": null,
"license": "Copyright (C) 2024 Novo Nordisk A/S",
"summary": "Checks the readability of markdown files in a directory and its subdirectories.",
"version": "2.0.0",
"project_urls": {
"Documentation": "https://github.com/innersource-nn/das-readability",
"Homepage": "https://github.com/innersource-nn/das-readability",
"Repository": "https://github.com/innersource-nn/das-readability"
},
"split_keywords": [
"readability",
" markdown",
" textstat",
" cli",
" smog",
" reading",
" ease",
" flesch"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a787de7a628087a237c505d6a7bd7fe15953af853c726aedb76bcd7f82aa82f0",
"md5": "2ea15dc86a59c362343ba2bfdd6528f2",
"sha256": "41ff43b9f997ff3faea9c5a8d78847eb1254131976b73cf68dd355154cf7e46b"
},
"downloads": -1,
"filename": "das_readability-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ea15dc86a59c362343ba2bfdd6528f2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.9.7",
"size": 5493,
"upload_time": "2024-04-19T09:46:27",
"upload_time_iso_8601": "2024-04-19T09:46:27.852759Z",
"url": "https://files.pythonhosted.org/packages/a7/87/de7a628087a237c505d6a7bd7fe15953af853c726aedb76bcd7f82aa82f0/das_readability-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5e33975666d83337d0d73fd239a83cbbfb5854b8ebab3d0602f88e7e25fef5d4",
"md5": "61a3006bcf8230495559f67cee327b9f",
"sha256": "7d39e6ea79b88b0f515d5d71e284f9c2cc62b0fed2104bf6a989cab78e92c0f7"
},
"downloads": -1,
"filename": "das_readability-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "61a3006bcf8230495559f67cee327b9f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0.0,>=3.9.7",
"size": 3877,
"upload_time": "2024-04-19T09:46:29",
"upload_time_iso_8601": "2024-04-19T09:46:29.787483Z",
"url": "https://files.pythonhosted.org/packages/5e/33/975666d83337d0d73fd239a83cbbfb5854b8ebab3d0602f88e7e25fef5d4/das_readability-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-19 09:46:29",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "innersource-nn",
"github_project": "das-readability",
"github_not_found": true,
"lcname": "das-readability"
}
JSON
