Code Monkey home page Code Monkey logo

docstr_coverage's Introduction

Docstr-Coverage

If the health of your documentation is in dire straits, docstr-coverage will see you now.

docstr-coverage is a simple tool that lets you measure your Python source code's docstring coverage. It can show you 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.

Example

>>> 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:

$ docstr-coverage some_module.py

To test a directory (recursively), just supply the directory some_project/src instead:

$ docstr-coverage some_project/src
Options:
  • --skipmagic, -m - Ignore all magic methods (like __init__, and __str__)
  • --skipfiledoc, -f - Ignore module docstrings (at the top of files)
  • --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)
    • 0 - Silence
    • 1 - Print overall statistics
    • 2 - Also print individual statistics for each file
    • 3 - Also print missing docstrings (function names, class names, etc.)

Package in Your Project

You can also use docstr-coverage as a part of your project by importing it thusly:

from docstr_coverage import get_docstring_coverage
my_coverage = get_docstring_coverage(['some_dir/file_0.py', 'some_dir/file_1.py'])
Arguments:
  • Required arg: filenames <list of string filenames>
  • Optional kwargs: skip_magic <bool>, skip_file_docstring <bool>, verbose <int (0-3)>
    • For more info on get_docstring_coverage and its parameters, please see its documentation
Results:

get_docstring_coverage returns two dicts: 1) stats for each file, and 2) total stats. For more info, please see the get_docstring_coverage documentation

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

pip install docstr-coverage

If you like being on the cutting-edge, and you want all the latest developments, run:

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.

docstr_coverage's People

Contributors

huntermcgushion avatar asergeant01 avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.