diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | python-docstr-coverage.spec | 784 | ||||
| -rw-r--r-- | sources | 1 |
3 files changed, 786 insertions, 0 deletions
@@ -0,0 +1 @@ +/docstr-coverage-2.2.0.tar.gz diff --git a/python-docstr-coverage.spec b/python-docstr-coverage.spec new file mode 100644 index 0000000..80ec3ba --- /dev/null +++ b/python-docstr-coverage.spec @@ -0,0 +1,784 @@ +%global _empty_manifest_terminate_build 0 +Name: python-docstr-coverage +Version: 2.2.0 +Release: 1 +Summary: Utility for examining python source files to ensure proper documentation. Lists missing docstrings, and calculates overall docstring coverage percentage rating. +License: MIT +URL: https://github.com/HunterMcGushion/docstr_coverage +Source0: https://mirrors.nju.edu.cn/pypi/web/packages/c4/27/4c7488507c249611859af99aa280ef531a30c44c19b427cff31d28af603d/docstr-coverage-2.2.0.tar.gz +BuildArch: noarch + +Requires: python3-click +Requires: python3-PyYAML +Requires: python3-flake8 +Requires: python3-black +Requires: python3-isort +Requires: python3-pytest +Requires: python3-pytest-mock + +%description + + +<p align="center"> + <a href="https://choosealicense.com/licenses/mit/" alt="License: MIT"> + <img src="https://img.shields.io/badge/license-MIT-green.svg" /></a> + <img src="https://github.com/HunterMcGushion/docstr_coverage/workflows/Python%20package/badge.svg" /> + <a href='https://docstr-coverage.readthedocs.io/en/latest/?badge=latest'> + <img src='https://readthedocs.org/projects/docstr-coverage/badge/?version=latest' alt='Documentation Status' /> + </a> + <a href="https://pypi.org/project/docstr-coverage/"> + <img alt="PyPI" src="https://img.shields.io/pypi/v/docstr-coverage"> + </a> + <a href="https://img.shields.io/pypi/pyversions/docstr-coverage"> + <img alt="Python Version" src="https://img.shields.io/pypi/pyversions/docstr-coverage"> + </a> + <a href="https://pepy.tech/project/docstr-coverage"> + <img alt="Download count" src="https://static.pepy.tech/personalized-badge/docstr-coverage?period=total&units=international_system&left_color=gray&right_color=orange&left_text=downloads"> + </a> + <a href="https://black.readthedocs.io/en/stable/" alt="Code Style: Black"> + <img src="https://img.shields.io/badge/code%20style-black-000000.svg" /> + </a> +</p> + +`docstr-coverage` is a simple tool that lets you measure your Python source code's +[docstring](http://www.python.org/dev/peps/pep-0257/#what-is-a-docstring) coverage. +It shows which of your functions, classes, methods, and modules don't have docstrings. +It also provide statistics about overall docstring coverage for individual files, and for your entire project. + +- [Source](https://github.com/HunterMcGushion/docstr_coverage) +- [Documentation](https://docstr-coverage.readthedocs.io/en/latest/api_essentials.html) + +## Example + +```bash +>>> HunterMcGushion$ docstr-coverage /docstr_coverage/ + +File: "docstr_coverage/setup.py" + - No module docstring + - No docstring for `readme` + Needed: 2; Found: 0; Missing: 2; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/__init__.py" + - No module docstring + Needed: 1; Found: 0; Missing: 1; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/coverage.py" + - No docstring for `DocStringCoverageVisitor.__init__` + Needed: 11; Found: 10; Missing: 1; Coverage: 90.9% + + +Overall statistics for 3 files: +Docstrings needed: 14; Docstrings found: 10; Docstrings missing: 4 +Total docstring coverage: 71.4%; Grade: Very good +``` + +## How Do I Use It + +### Command-line Tool + +General usage is: `docstr-coverage <path to dir or module> [options]` + +To test a single module, named `some_module.py`, run: + +```bash +docstr-coverage some_module.py +``` + +To test a directory (recursively), just supply the directory `some_project/src` instead: + +```bash +docstr-coverage some_project/src +``` + +#### Options + +- _--skip-magic, -m_ - Ignore all magic methods (except `__init__`) +- _--skip-init, -i_ - Ignore all `__init__` methods +- _--skip-file-doc, -f_ - Ignore module docstrings (at the top of files) +- _--skip-private, -P_ - Ignore private functions (starting with a single underscore) +- _--skip-class-def, -c_ - Ignore docstrings of class definitions +- _--skip-property, -sp_ - Ignore functions with `@property` decorator +- _--include-setter, -is_ - Include functions with `@setter` decorator (skipped by default) +- _--include-deleter, -idel_ - Include functions with `@deleter` decorator (skipped by default) +- _--accept-empty, -a_ - Exit with code 0 if no Python files are found (default: exit code 1) +- _--exclude=\<regex\>, -e \<regex\>_ - Filepath pattern to exclude from analysis + - To exclude the contents of a virtual environment `env` and your `tests` directory, run: + ```docstr-coverage some_project/ -e ".*/(env|tests)"``` +- _--verbose=\<level\>, -v \<level\>_ - Set verbosity level (0-3, default: 3) + - 0 - Silence + - 1 - Print overall statistics + - 2 - Also print individual statistics for each file + - 3 - Also print missing docstrings (function names, class names, etc.) + - 4 - Also print information about present docstrings +- _--fail-under=<int|float>, -F <int|float>_ - Fail if under a certain percentage of coverage (default: 100.0) +- _--docstr-ignore-file=\<filepath\>, -d \<filepath\>_ - Filepath containing list of patterns to ignore. Patterns are (file-pattern, name-pattern) pairs + - File content example: + + ``` + SomeFile method_to_ignore1 method_to_ignore2 method_to_ignore3 + FileWhereWeWantToIgnoreAllSpecialMethods __.+__ + .* method_to_ignore_in_all_files + a_very_important_view_file ^get$ ^set$ ^post$ + detect_.* get_val.* + ``` +- _--badge=\<filepath\>, -b \<filepath\>_ - Generate a docstring coverage percent badge as an SVG saved to a given filepath + - Include the badge in a repo's README using + ```[](https://github.com/HunterMcGushion/docstr_coverage)```, + where `<filepath/of/your/saved/badge.svg>` is the path provided to the `--badge` option +- _--follow-links, -l_ - Follow symlinks +- _--percentage-only, -p_ - Output only the overall coverage percentage as a float, silencing all other logging +- _--help, -h_ - Display CLI options + +#### Config File +All options can be saved in a config file. A file named `.docstr.yaml` in the folder in which `docstr-coverage` is executed is picked up automatically. +Other locations can be passed using `docstr-coverage -C path/to/config.json` or the long version `--config`. + +Example: +```yaml +paths: # list or string + - docstr_coverage +badge: docs # Path +exclude: .*/test # regex +verbose: 3 # int (0-4) +skip_magic: True # Boolean +skip_file_doc: True # Boolean +skip_init: True # Boolean +skip_class_def: True # Boolean +skip_private: True # Boolean +follow_links: True # Boolean +accept_empty: True # Boolean +ignore_names_file: .*/test # regex +fail_under: 90 # int +percentage_only: True # Boolean +ignore_patterns: # Dict with key/value pairs of file-pattern/node-pattern + .*: method_to_ignore_in_all_files + FileWhereWeWantToIgnoreAllSpecialMethods: "__.+__" + SomeFile: + - method_to_ignore1 + - method_to_ignore2 + - method_to_ignore3 + a_very_important_view_file: + - "^get$" + - "^set$" + - "^post$" + detect_.*: + - "get_val.*" +``` +equivalent to +``` +docstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="docs" --skip-class-def etc... +``` + +Note that options passed as command line arguments have precedence over options +configured in a config file. +Exception: If a `--docstr-ignore-file` is present and the yml config contains `ignore_patterns`, +a `ValueError` is raised. + +#### Overriding by Comments +Note that `docstr-coverage` can not parse +dynamically added documentation (e.g. through class extension). +Thus, some of your code which deliberately has no docstring might be counted as uncovered. + +You can override this by adding either ```# docstr-coverage:inherited``` +(intended for use if a docstring is provided in the corresponding superclass method) +or a generic excuse with a reason, like ```# docstr-coverage:excused `My probably bad excuse` ```. +These have to be stated right above any class or function definition +(or above the functions annotations, if applicable). +Such class or function would then be counted as if they had a docstring. + +```python +# docstr-coverage:excused `no one is reading this anyways` +class FooBarChild(FooBar): + + # docstr-coverage:inherited + def function(self): + pass +``` + +#### Pre-commit hook + +You can use `docstr-coverage` as a pre-commit hook by adding the following to your `.pre-commit-config.yaml` file +and configuring the `paths` section of the [`.docstr.yaml` config](#config-file). + This is preferrable over [pre-commit args](https://pre-commit.com/#config-args), + as it facilitates the use of the same config in CI, pre-commit and manual runs. + +```yaml +repos: + - repo: https://github.com/HunterMcGushion/docstr_coverage + rev: v2.2.0 # most recent docstr-coverage release or commit sha + hooks: + - id: docstr-coverage + args: ["--verbose", "2"] # override the .docstr.yaml to see less output +``` + +#### Package in Your Project + +You can also use `docstr-coverage` as a part of your project by importing it thusly. +It will supply you with overall and per-file coverages: + +```python +from docstr_coverage import get_docstring_coverage +my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py']) +``` + +If you want more fine grained information, try the experimental `docstr_coverage.analyze()` +```python +from docstr_coverage import analyze +coverage_report = analyze(['some_dir/file_0.py', 'some_dir/file_1.py']) +coverage = coverage_report.count_aggregate().coverage() +``` + +## Why Should I Use It + +- Thorough documentation is important to help others (and even yourself) understand your code +- As a developer, improve your code's maintainability for when you need to make updates and fix bugs +- As a user, instantly know how easy it's going to be to understand a new library \* If its documentation coverage is low, you may need to figure a lot out for yourself + +## Installation + +```bash +pip install docstr-coverage +``` + +If you like being on the cutting-edge, and you want all the latest developments, run: + +```bash +pip install git+https://github.com/HunterMcGushion/docstr_coverage.git +``` + +## Special Thanks + +Thank you to Alexey "DataGreed" Strelkov, and James Harlow for doing all the hard work. +`docstr-coverage` simply revives and brings their efforts to Python 3. See 'THANKS.txt' for more information. + + + + +%package -n python3-docstr-coverage +Summary: Utility for examining python source files to ensure proper documentation. Lists missing docstrings, and calculates overall docstring coverage percentage rating. +Provides: python-docstr-coverage +BuildRequires: python3-devel +BuildRequires: python3-setuptools +BuildRequires: python3-pip +%description -n python3-docstr-coverage + + +<p align="center"> + <a href="https://choosealicense.com/licenses/mit/" alt="License: MIT"> + <img src="https://img.shields.io/badge/license-MIT-green.svg" /></a> + <img src="https://github.com/HunterMcGushion/docstr_coverage/workflows/Python%20package/badge.svg" /> + <a href='https://docstr-coverage.readthedocs.io/en/latest/?badge=latest'> + <img src='https://readthedocs.org/projects/docstr-coverage/badge/?version=latest' alt='Documentation Status' /> + </a> + <a href="https://pypi.org/project/docstr-coverage/"> + <img alt="PyPI" src="https://img.shields.io/pypi/v/docstr-coverage"> + </a> + <a href="https://img.shields.io/pypi/pyversions/docstr-coverage"> + <img alt="Python Version" src="https://img.shields.io/pypi/pyversions/docstr-coverage"> + </a> + <a href="https://pepy.tech/project/docstr-coverage"> + <img alt="Download count" src="https://static.pepy.tech/personalized-badge/docstr-coverage?period=total&units=international_system&left_color=gray&right_color=orange&left_text=downloads"> + </a> + <a href="https://black.readthedocs.io/en/stable/" alt="Code Style: Black"> + <img src="https://img.shields.io/badge/code%20style-black-000000.svg" /> + </a> +</p> + +`docstr-coverage` is a simple tool that lets you measure your Python source code's +[docstring](http://www.python.org/dev/peps/pep-0257/#what-is-a-docstring) coverage. +It shows which of your functions, classes, methods, and modules don't have docstrings. +It also provide statistics about overall docstring coverage for individual files, and for your entire project. + +- [Source](https://github.com/HunterMcGushion/docstr_coverage) +- [Documentation](https://docstr-coverage.readthedocs.io/en/latest/api_essentials.html) + +## Example + +```bash +>>> HunterMcGushion$ docstr-coverage /docstr_coverage/ + +File: "docstr_coverage/setup.py" + - No module docstring + - No docstring for `readme` + Needed: 2; Found: 0; Missing: 2; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/__init__.py" + - No module docstring + Needed: 1; Found: 0; Missing: 1; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/coverage.py" + - No docstring for `DocStringCoverageVisitor.__init__` + Needed: 11; Found: 10; Missing: 1; Coverage: 90.9% + + +Overall statistics for 3 files: +Docstrings needed: 14; Docstrings found: 10; Docstrings missing: 4 +Total docstring coverage: 71.4%; Grade: Very good +``` + +## How Do I Use It + +### Command-line Tool + +General usage is: `docstr-coverage <path to dir or module> [options]` + +To test a single module, named `some_module.py`, run: + +```bash +docstr-coverage some_module.py +``` + +To test a directory (recursively), just supply the directory `some_project/src` instead: + +```bash +docstr-coverage some_project/src +``` + +#### Options + +- _--skip-magic, -m_ - Ignore all magic methods (except `__init__`) +- _--skip-init, -i_ - Ignore all `__init__` methods +- _--skip-file-doc, -f_ - Ignore module docstrings (at the top of files) +- _--skip-private, -P_ - Ignore private functions (starting with a single underscore) +- _--skip-class-def, -c_ - Ignore docstrings of class definitions +- _--skip-property, -sp_ - Ignore functions with `@property` decorator +- _--include-setter, -is_ - Include functions with `@setter` decorator (skipped by default) +- _--include-deleter, -idel_ - Include functions with `@deleter` decorator (skipped by default) +- _--accept-empty, -a_ - Exit with code 0 if no Python files are found (default: exit code 1) +- _--exclude=\<regex\>, -e \<regex\>_ - Filepath pattern to exclude from analysis + - To exclude the contents of a virtual environment `env` and your `tests` directory, run: + ```docstr-coverage some_project/ -e ".*/(env|tests)"``` +- _--verbose=\<level\>, -v \<level\>_ - Set verbosity level (0-3, default: 3) + - 0 - Silence + - 1 - Print overall statistics + - 2 - Also print individual statistics for each file + - 3 - Also print missing docstrings (function names, class names, etc.) + - 4 - Also print information about present docstrings +- _--fail-under=<int|float>, -F <int|float>_ - Fail if under a certain percentage of coverage (default: 100.0) +- _--docstr-ignore-file=\<filepath\>, -d \<filepath\>_ - Filepath containing list of patterns to ignore. Patterns are (file-pattern, name-pattern) pairs + - File content example: + + ``` + SomeFile method_to_ignore1 method_to_ignore2 method_to_ignore3 + FileWhereWeWantToIgnoreAllSpecialMethods __.+__ + .* method_to_ignore_in_all_files + a_very_important_view_file ^get$ ^set$ ^post$ + detect_.* get_val.* + ``` +- _--badge=\<filepath\>, -b \<filepath\>_ - Generate a docstring coverage percent badge as an SVG saved to a given filepath + - Include the badge in a repo's README using + ```[](https://github.com/HunterMcGushion/docstr_coverage)```, + where `<filepath/of/your/saved/badge.svg>` is the path provided to the `--badge` option +- _--follow-links, -l_ - Follow symlinks +- _--percentage-only, -p_ - Output only the overall coverage percentage as a float, silencing all other logging +- _--help, -h_ - Display CLI options + +#### Config File +All options can be saved in a config file. A file named `.docstr.yaml` in the folder in which `docstr-coverage` is executed is picked up automatically. +Other locations can be passed using `docstr-coverage -C path/to/config.json` or the long version `--config`. + +Example: +```yaml +paths: # list or string + - docstr_coverage +badge: docs # Path +exclude: .*/test # regex +verbose: 3 # int (0-4) +skip_magic: True # Boolean +skip_file_doc: True # Boolean +skip_init: True # Boolean +skip_class_def: True # Boolean +skip_private: True # Boolean +follow_links: True # Boolean +accept_empty: True # Boolean +ignore_names_file: .*/test # regex +fail_under: 90 # int +percentage_only: True # Boolean +ignore_patterns: # Dict with key/value pairs of file-pattern/node-pattern + .*: method_to_ignore_in_all_files + FileWhereWeWantToIgnoreAllSpecialMethods: "__.+__" + SomeFile: + - method_to_ignore1 + - method_to_ignore2 + - method_to_ignore3 + a_very_important_view_file: + - "^get$" + - "^set$" + - "^post$" + detect_.*: + - "get_val.*" +``` +equivalent to +``` +docstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="docs" --skip-class-def etc... +``` + +Note that options passed as command line arguments have precedence over options +configured in a config file. +Exception: If a `--docstr-ignore-file` is present and the yml config contains `ignore_patterns`, +a `ValueError` is raised. + +#### Overriding by Comments +Note that `docstr-coverage` can not parse +dynamically added documentation (e.g. through class extension). +Thus, some of your code which deliberately has no docstring might be counted as uncovered. + +You can override this by adding either ```# docstr-coverage:inherited``` +(intended for use if a docstring is provided in the corresponding superclass method) +or a generic excuse with a reason, like ```# docstr-coverage:excused `My probably bad excuse` ```. +These have to be stated right above any class or function definition +(or above the functions annotations, if applicable). +Such class or function would then be counted as if they had a docstring. + +```python +# docstr-coverage:excused `no one is reading this anyways` +class FooBarChild(FooBar): + + # docstr-coverage:inherited + def function(self): + pass +``` + +#### Pre-commit hook + +You can use `docstr-coverage` as a pre-commit hook by adding the following to your `.pre-commit-config.yaml` file +and configuring the `paths` section of the [`.docstr.yaml` config](#config-file). + This is preferrable over [pre-commit args](https://pre-commit.com/#config-args), + as it facilitates the use of the same config in CI, pre-commit and manual runs. + +```yaml +repos: + - repo: https://github.com/HunterMcGushion/docstr_coverage + rev: v2.2.0 # most recent docstr-coverage release or commit sha + hooks: + - id: docstr-coverage + args: ["--verbose", "2"] # override the .docstr.yaml to see less output +``` + +#### Package in Your Project + +You can also use `docstr-coverage` as a part of your project by importing it thusly. +It will supply you with overall and per-file coverages: + +```python +from docstr_coverage import get_docstring_coverage +my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py']) +``` + +If you want more fine grained information, try the experimental `docstr_coverage.analyze()` +```python +from docstr_coverage import analyze +coverage_report = analyze(['some_dir/file_0.py', 'some_dir/file_1.py']) +coverage = coverage_report.count_aggregate().coverage() +``` + +## Why Should I Use It + +- Thorough documentation is important to help others (and even yourself) understand your code +- As a developer, improve your code's maintainability for when you need to make updates and fix bugs +- As a user, instantly know how easy it's going to be to understand a new library \* If its documentation coverage is low, you may need to figure a lot out for yourself + +## Installation + +```bash +pip install docstr-coverage +``` + +If you like being on the cutting-edge, and you want all the latest developments, run: + +```bash +pip install git+https://github.com/HunterMcGushion/docstr_coverage.git +``` + +## Special Thanks + +Thank you to Alexey "DataGreed" Strelkov, and James Harlow for doing all the hard work. +`docstr-coverage` simply revives and brings their efforts to Python 3. See 'THANKS.txt' for more information. + + + + +%package help +Summary: Development documents and examples for docstr-coverage +Provides: python3-docstr-coverage-doc +%description help + + +<p align="center"> + <a href="https://choosealicense.com/licenses/mit/" alt="License: MIT"> + <img src="https://img.shields.io/badge/license-MIT-green.svg" /></a> + <img src="https://github.com/HunterMcGushion/docstr_coverage/workflows/Python%20package/badge.svg" /> + <a href='https://docstr-coverage.readthedocs.io/en/latest/?badge=latest'> + <img src='https://readthedocs.org/projects/docstr-coverage/badge/?version=latest' alt='Documentation Status' /> + </a> + <a href="https://pypi.org/project/docstr-coverage/"> + <img alt="PyPI" src="https://img.shields.io/pypi/v/docstr-coverage"> + </a> + <a href="https://img.shields.io/pypi/pyversions/docstr-coverage"> + <img alt="Python Version" src="https://img.shields.io/pypi/pyversions/docstr-coverage"> + </a> + <a href="https://pepy.tech/project/docstr-coverage"> + <img alt="Download count" src="https://static.pepy.tech/personalized-badge/docstr-coverage?period=total&units=international_system&left_color=gray&right_color=orange&left_text=downloads"> + </a> + <a href="https://black.readthedocs.io/en/stable/" alt="Code Style: Black"> + <img src="https://img.shields.io/badge/code%20style-black-000000.svg" /> + </a> +</p> + +`docstr-coverage` is a simple tool that lets you measure your Python source code's +[docstring](http://www.python.org/dev/peps/pep-0257/#what-is-a-docstring) coverage. +It shows which of your functions, classes, methods, and modules don't have docstrings. +It also provide statistics about overall docstring coverage for individual files, and for your entire project. + +- [Source](https://github.com/HunterMcGushion/docstr_coverage) +- [Documentation](https://docstr-coverage.readthedocs.io/en/latest/api_essentials.html) + +## Example + +```bash +>>> HunterMcGushion$ docstr-coverage /docstr_coverage/ + +File: "docstr_coverage/setup.py" + - No module docstring + - No docstring for `readme` + Needed: 2; Found: 0; Missing: 2; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/__init__.py" + - No module docstring + Needed: 1; Found: 0; Missing: 1; Coverage: 0.0% + +File: "docstr_coverage/docstr_coverage/coverage.py" + - No docstring for `DocStringCoverageVisitor.__init__` + Needed: 11; Found: 10; Missing: 1; Coverage: 90.9% + + +Overall statistics for 3 files: +Docstrings needed: 14; Docstrings found: 10; Docstrings missing: 4 +Total docstring coverage: 71.4%; Grade: Very good +``` + +## How Do I Use It + +### Command-line Tool + +General usage is: `docstr-coverage <path to dir or module> [options]` + +To test a single module, named `some_module.py`, run: + +```bash +docstr-coverage some_module.py +``` + +To test a directory (recursively), just supply the directory `some_project/src` instead: + +```bash +docstr-coverage some_project/src +``` + +#### Options + +- _--skip-magic, -m_ - Ignore all magic methods (except `__init__`) +- _--skip-init, -i_ - Ignore all `__init__` methods +- _--skip-file-doc, -f_ - Ignore module docstrings (at the top of files) +- _--skip-private, -P_ - Ignore private functions (starting with a single underscore) +- _--skip-class-def, -c_ - Ignore docstrings of class definitions +- _--skip-property, -sp_ - Ignore functions with `@property` decorator +- _--include-setter, -is_ - Include functions with `@setter` decorator (skipped by default) +- _--include-deleter, -idel_ - Include functions with `@deleter` decorator (skipped by default) +- _--accept-empty, -a_ - Exit with code 0 if no Python files are found (default: exit code 1) +- _--exclude=\<regex\>, -e \<regex\>_ - Filepath pattern to exclude from analysis + - To exclude the contents of a virtual environment `env` and your `tests` directory, run: + ```docstr-coverage some_project/ -e ".*/(env|tests)"``` +- _--verbose=\<level\>, -v \<level\>_ - Set verbosity level (0-3, default: 3) + - 0 - Silence + - 1 - Print overall statistics + - 2 - Also print individual statistics for each file + - 3 - Also print missing docstrings (function names, class names, etc.) + - 4 - Also print information about present docstrings +- _--fail-under=<int|float>, -F <int|float>_ - Fail if under a certain percentage of coverage (default: 100.0) +- _--docstr-ignore-file=\<filepath\>, -d \<filepath\>_ - Filepath containing list of patterns to ignore. Patterns are (file-pattern, name-pattern) pairs + - File content example: + + ``` + SomeFile method_to_ignore1 method_to_ignore2 method_to_ignore3 + FileWhereWeWantToIgnoreAllSpecialMethods __.+__ + .* method_to_ignore_in_all_files + a_very_important_view_file ^get$ ^set$ ^post$ + detect_.* get_val.* + ``` +- _--badge=\<filepath\>, -b \<filepath\>_ - Generate a docstring coverage percent badge as an SVG saved to a given filepath + - Include the badge in a repo's README using + ```[](https://github.com/HunterMcGushion/docstr_coverage)```, + where `<filepath/of/your/saved/badge.svg>` is the path provided to the `--badge` option +- _--follow-links, -l_ - Follow symlinks +- _--percentage-only, -p_ - Output only the overall coverage percentage as a float, silencing all other logging +- _--help, -h_ - Display CLI options + +#### Config File +All options can be saved in a config file. A file named `.docstr.yaml` in the folder in which `docstr-coverage` is executed is picked up automatically. +Other locations can be passed using `docstr-coverage -C path/to/config.json` or the long version `--config`. + +Example: +```yaml +paths: # list or string + - docstr_coverage +badge: docs # Path +exclude: .*/test # regex +verbose: 3 # int (0-4) +skip_magic: True # Boolean +skip_file_doc: True # Boolean +skip_init: True # Boolean +skip_class_def: True # Boolean +skip_private: True # Boolean +follow_links: True # Boolean +accept_empty: True # Boolean +ignore_names_file: .*/test # regex +fail_under: 90 # int +percentage_only: True # Boolean +ignore_patterns: # Dict with key/value pairs of file-pattern/node-pattern + .*: method_to_ignore_in_all_files + FileWhereWeWantToIgnoreAllSpecialMethods: "__.+__" + SomeFile: + - method_to_ignore1 + - method_to_ignore2 + - method_to_ignore3 + a_very_important_view_file: + - "^get$" + - "^set$" + - "^post$" + detect_.*: + - "get_val.*" +``` +equivalent to +``` +docstr-coverage docstr_coverage -e ".*/test" --skip-magic --skip-init --badge="docs" --skip-class-def etc... +``` + +Note that options passed as command line arguments have precedence over options +configured in a config file. +Exception: If a `--docstr-ignore-file` is present and the yml config contains `ignore_patterns`, +a `ValueError` is raised. + +#### Overriding by Comments +Note that `docstr-coverage` can not parse +dynamically added documentation (e.g. through class extension). +Thus, some of your code which deliberately has no docstring might be counted as uncovered. + +You can override this by adding either ```# docstr-coverage:inherited``` +(intended for use if a docstring is provided in the corresponding superclass method) +or a generic excuse with a reason, like ```# docstr-coverage:excused `My probably bad excuse` ```. +These have to be stated right above any class or function definition +(or above the functions annotations, if applicable). +Such class or function would then be counted as if they had a docstring. + +```python +# docstr-coverage:excused `no one is reading this anyways` +class FooBarChild(FooBar): + + # docstr-coverage:inherited + def function(self): + pass +``` + +#### Pre-commit hook + +You can use `docstr-coverage` as a pre-commit hook by adding the following to your `.pre-commit-config.yaml` file +and configuring the `paths` section of the [`.docstr.yaml` config](#config-file). + This is preferrable over [pre-commit args](https://pre-commit.com/#config-args), + as it facilitates the use of the same config in CI, pre-commit and manual runs. + +```yaml +repos: + - repo: https://github.com/HunterMcGushion/docstr_coverage + rev: v2.2.0 # most recent docstr-coverage release or commit sha + hooks: + - id: docstr-coverage + args: ["--verbose", "2"] # override the .docstr.yaml to see less output +``` + +#### Package in Your Project + +You can also use `docstr-coverage` as a part of your project by importing it thusly. +It will supply you with overall and per-file coverages: + +```python +from docstr_coverage import get_docstring_coverage +my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py']) +``` + +If you want more fine grained information, try the experimental `docstr_coverage.analyze()` +```python +from docstr_coverage import analyze +coverage_report = analyze(['some_dir/file_0.py', 'some_dir/file_1.py']) +coverage = coverage_report.count_aggregate().coverage() +``` + +## Why Should I Use It + +- Thorough documentation is important to help others (and even yourself) understand your code +- As a developer, improve your code's maintainability for when you need to make updates and fix bugs +- As a user, instantly know how easy it's going to be to understand a new library \* If its documentation coverage is low, you may need to figure a lot out for yourself + +## Installation + +```bash +pip install docstr-coverage +``` + +If you like being on the cutting-edge, and you want all the latest developments, run: + +```bash +pip install git+https://github.com/HunterMcGushion/docstr_coverage.git +``` + +## Special Thanks + +Thank you to Alexey "DataGreed" Strelkov, and James Harlow for doing all the hard work. +`docstr-coverage` simply revives and brings their efforts to Python 3. See 'THANKS.txt' for more information. + + + + +%prep +%autosetup -n docstr-coverage-2.2.0 + +%build +%py3_build + +%install +%py3_install +install -d -m755 %{buildroot}/%{_pkgdocdir} +if [ -d doc ]; then cp -arf doc %{buildroot}/%{_pkgdocdir}; fi +if [ -d docs ]; then cp -arf docs %{buildroot}/%{_pkgdocdir}; fi +if [ -d example ]; then cp -arf example %{buildroot}/%{_pkgdocdir}; fi +if [ -d examples ]; then cp -arf examples %{buildroot}/%{_pkgdocdir}; fi +pushd %{buildroot} +if [ -d usr/lib ]; then + find usr/lib -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/lib64 ]; then + find usr/lib64 -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/bin ]; then + find usr/bin -type f -printf "/%h/%f\n" >> filelist.lst +fi +if [ -d usr/sbin ]; then + find usr/sbin -type f -printf "/%h/%f\n" >> filelist.lst +fi +touch doclist.lst +if [ -d usr/share/man ]; then + find usr/share/man -type f -printf "/%h/%f.gz\n" >> doclist.lst +fi +popd +mv %{buildroot}/filelist.lst . +mv %{buildroot}/doclist.lst . + +%files -n python3-docstr-coverage -f filelist.lst +%dir %{python3_sitelib}/* + +%files help -f doclist.lst +%{_docdir}/* + +%changelog +* Wed Apr 12 2023 Python_Bot <Python_Bot@openeuler.org> - 2.2.0-1 +- Package Spec generated @@ -0,0 +1 @@ +1d4bd208d195e5402b8682a5f1532bff docstr-coverage-2.2.0.tar.gz |