Metadata-Version: 2.4
Name: cjm-nbdev-docments
Version: 0.0.1
Summary: Tool for validating and updating documentation in nbdev projects for use with the fastcore.docments module.
Home-page: https://github.com/cj-mills/cjm-nbdev-docments
Author: Christian J. Mills
Author-email: 9126128+cj-mills@users.noreply.github.com
License: Apache Software License 2.0
Keywords: nbdev jupyter notebook python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: Apache Software License
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastcore
Requires-Dist: nbdev
Requires-Dist: execnb
Provides-Extra: dev
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# cjm-nbdev-docments


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Overview

`cjm-nbdev-docments` helps nbdev users adopt and maintain the
[fastcore.docments](https://fastcore.fast.ai/docments.html)
documentation style. Instead of traditional docstrings, `docments` uses
inline parameter documentation, making code more concise and readable.

### What is docments style?

Instead of this:

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

``` python
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](https://github.com/cj-mills/cjm-nbdev-docments):

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

or from [conda](https://anaconda.org/cj-mills/cjm-nbdev-docments)

``` sh
$ conda install -c cj-mills cjm_nbdev_docments
```

or from [pypi](https://pypi.org/project/cjm-nbdev-docments/)

``` sh
$ pip install cjm_nbdev_docments
```

## Quick Start

### Basic Usage

Check your nbdev project for documentation compliance:

``` bash
# 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:

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

# Apply fixes
nbdev-docments --fix
```

### Converting Existing Docstrings

Convert traditional docstrings to docments format:

``` bash
# 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:

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

``` python
from cjm_nbdev_docments.core import check_notebook

check_notebook("00_core.ipynb")
```

### Programmatic Usage

For integration into your own tools:

``` python
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`](https://cj-mills.github.io/cjm-nbdev-docments/core.html#docmentscheckresult):
Data class for storing compliance check results -
[`check_definition`](https://cj-mills.github.io/cjm-nbdev-docments/core.html#check_definition):
Check a function/class for compliance -
[`check_function`](https://cj-mills.github.io/cjm-nbdev-docments/core.html#check_function):
Check a single function object -
[`check_notebook`](https://cj-mills.github.io/cjm-nbdev-docments/core.html#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`](https://cj-mills.github.io/cjm-nbdev-docments/scanner.html#scan_notebook):
Extract all exported definitions from a notebook -
[`scan_project`](https://cj-mills.github.io/cjm-nbdev-docments/scanner.html#scan_project):
Scan all notebooks in an nbdev project -
[`get_export_cells`](https://cj-mills.github.io/cjm-nbdev-docments/scanner.html#get_export_cells):
Find cells with nbdev export directives

### 3. **Report** (`cjm_nbdev_docments.report`)

Generates compliance reports for docments validation. Provides: -
[`check_project`](https://cj-mills.github.io/cjm-nbdev-docments/report.html#check_project):
Check all definitions in a project -
[`generate_text_report`](https://cj-mills.github.io/cjm-nbdev-docments/report.html#generate_text_report):
Create human-readable compliance reports -
[`generate_json_report`](https://cj-mills.github.io/cjm-nbdev-docments/report.html#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](https://github.com/cj-mills/cjm-nbdev-docments)’s
[pages](https://cj-mills.github.io/cjm-nbdev-docments/). Additionally
you can find package manager specific guidelines on
[conda](https://anaconda.org/cj-mills/cjm-nbdev-docments) and
[pypi](https://pypi.org/project/cjm-nbdev-docments/) respectively.
