cjm-nbdev-docments 0.0.1

Tool for validating and updating documentation in nbdev projects for use with the fastcore.docments module.

cjm-nbdev-docments

Overview

cjm-nbdev-docments helps nbdev users adopt and maintain the fastcore.docments documentation style. Instead of traditional docstrings, docments uses inline parameter documentation, making code more concise and readable.

What is docments style?

Instead of this:

def add(x, y):
    """Add two numbers.
    
    Args:
        x: First number
        y: Second number
        
    Returns:
        Sum of x and y
    """
    return x + y

Docments style looks like this:

def add(
    x: int,  # First number
    y: int   # Second number  
) -> int:  # Sum of x and y
    "Add two numbers"
    return x + y

Key Features

• 🔍 Comprehensive Scanning: Automatically scans all exported functions and classes in your nbdev notebooks
• ✅ Compliance Checking: Verifies that all parameters and return values have proper documentation
• 📊 Detailed Reports: Generate text or JSON reports showing compliance status
• 🔧 Auto-fix Support: Automatically add TODO placeholders for missing documentation
• 🔄 Docstring Conversion: Convert existing Google/NumPy/Sphinx style docstrings to docments format
• 💻 CLI Interface: Easy-to-use command-line tool integrated with nbdev workflow

Installation

Install latest from the GitHub repository:

$ pip install git+https://github.com/cj-mills/cjm-nbdev-docments.git

or from conda

$ conda install -c cj-mills cjm_nbdev_docments

or from pypi

$ pip install cjm_nbdev_docments

Quick Start

Basic Usage

Check your nbdev project for documentation compliance:

# Check all notebooks in your project
nbdev-docments

# Get detailed report including compliant functions
nbdev-docments --verbose

# Save report to a file
nbdev-docments --output compliance-report.txt

Auto-fixing Non-compliant Code

Automatically add TODO placeholders for missing documentation:

# Preview what would be fixed
nbdev-docments --fix --dry-run

# Apply fixes
nbdev-docments --fix

Converting Existing Docstrings

Convert traditional docstrings to docments format:

# Convert Google/NumPy/Sphinx style docstrings
nbdev-docments --fix --convert-docstrings

Detailed Usage Examples

Checking a Single Function

You can check individual functions for compliance:

from cjm_nbdev_docments.core import check_function

def example_func(x, y):
    return x + y

check_function(example_func)

Checking a Specific Notebook

Check a single notebook file:

from cjm_nbdev_docments.core import check_notebook

check_notebook("00_core.ipynb")

Programmatic Usage

For integration into your own tools:

from cjm_nbdev_docments.report import check_project, generate_json_report

# Check entire project
results = check_project()

# Generate JSON report
report = generate_json_report(results)

# Process results programmatically
for notebook, data in report['by_notebook'].items():
    print(f"{notebook}: {len(data['non_compliant'])} issues")

What Gets Checked?

The tool checks for:

1. Function/Method Documentation:
   • Presence of a docstring
   • Documentation for each parameter (except self)
   • Documentation for return values (when return type is annotated)
2. Type Hints:
   • Missing type annotations for parameters
   • Missing return type annotations
3. Class Documentation:
   • Presence of class docstrings
4. TODO Tracking:
   • Identifies documentation with TODO placeholders
   • Helps track documentation debt

CLI Reference

nbdev-docments [OPTIONS]

Options:
  --nbs-path PATH           Path to notebooks directory (defaults to nbdev config)
  --format {text,json}      Output format (default: text)
  --output, -o PATH         Save report to file instead of printing
  --verbose, -v             Show compliant definitions in text report
  --quiet, -q               Only show summary (exit code indicates compliance)
  --todos-only              Show only functions with TODO placeholders
  --fix                     Auto-fix non-compliant functions by adding placeholder docs
  --convert-docstrings      Convert existing Google/NumPy/Sphinx docstrings to docments format
  --dry-run                 Show what would be fixed without making changes
  -h, --help                Show help message and exit

Exit Codes

• 0: All checked definitions are compliant
• 1: One or more definitions are non-compliant

Module Overview

The package consists of five main modules:

1. Core (cjm_nbdev_docments.core)

Core functionality for checking docments compliance. This module provides: - DocmentsCheckResult: Data class for storing compliance check results - check_definition: Check a function/class for compliance - check_function: Check a single function object - check_notebook: Check all definitions in a notebook

2. Scanner (cjm_nbdev_docments.scanner)

Scans nbdev notebooks for exported functions and classes. Key functions: - scan_notebook: Extract all exported definitions from a notebook - scan_project: Scan all notebooks in an nbdev project - get_export_cells: Find cells with nbdev export directives

3. Report (cjm_nbdev_docments.report)

Generates compliance reports for docments validation. Provides: - check_project: Check all definitions in a project - generate_text_report: Create human-readable compliance reports - generate_json_report: Create machine-readable JSON reports

4. Autofix (cjm_nbdev_docments.autofix)

Automatically adds placeholder documentation to non-compliant functions. Features: - fix_notebook: Add TODO placeholders for missing documentation - generate_fixed_source: Generate corrected source code - Docstring conversion from Google/NumPy/Sphinx to docments format

5. CLI (cjm_nbdev_docments.cli)

Command-line interface for docments compliance checking. The nbdev-docments command provides easy access to all functionality.

Documentation

Documentation can be found hosted on this GitHub repository’s pages. Additionally you can find package manager specific guidelines on conda and pypi respectively.