API Documentation Generation

Generate module overviews with formatted signatures for nbdev projects

Formatting Functions

format_function_doc

 format_function_doc (func:cjm_nbdev_overview.parsers.FunctionInfo,
                      indent:str='')

Format a function with its signature for documentation

	Type	Details
func	FunctionInfo	Function information
indent	str	Indentation prefix
Returns	str	Formatted documentation

source

format_class_doc

 format_class_doc (cls:cjm_nbdev_overview.parsers.ClassInfo)

Format a class with its signature and methods for documentation

	Type	Details
cls	ClassInfo	Class information
Returns	str	Formatted documentation

source

format_variable_doc

 format_variable_doc (var:cjm_nbdev_overview.parsers.VariableInfo)

Format a variable for documentation

	Type	Details
var	VariableInfo	Variable information
Returns	str	Formatted documentation

Module Documentation Generation

source

generate_module_overview

 generate_module_overview (module:cjm_nbdev_overview.parsers.ModuleInfo,
                           show_all:bool=False)

Generate a markdown overview for a module

	Type	Default	Details
module	ModuleInfo		Module information
show_all	bool	False	Show all items including private
Returns	str		Module overview markdown

source

generate_project_api_docs

 generate_project_api_docs (path:pathlib.Path=None, show_all:bool=False)

Generate API documentation for all modules in a project

	Type	Default	Details
path	Path	None	Project path (defaults to nbs_path)
show_all	bool	False	Show all items including private
Returns	str		Full API documentation

Index Update Function

The update_index_module_docs function can automatically update your project’s index.ipynb with module documentation:

source

update_index_module_docs

 update_index_module_docs (index_path:pathlib.Path=None,
                           start_marker:str='## Module Overview')

Update the module documentation section in index.ipynb

	Type	Default	Details
index_path	Path	None	Path to index.ipynb (defaults to nbs/index.ipynb)
start_marker	str	## Module Overview	Marker to identify module docs section
Returns	None		Updates index.ipynb in place

# Example: Update the index.ipynb with module documentation
# update_index_module_docs()  # This will update nbs/index.ipynb

# Or specify a custom path:
# update_index_module_docs(Path("../other_project/nbs/index.ipynb"))

Comprehensive Index Update Functions

Additional functions to update index.ipynb with project structure, dependencies, CLI reference, and statistics:

source

add_project_structure_section

 add_project_structure_section (index_path:pathlib.Path=None,
                                marker:str='## Project Structure',
                                exclude_index:bool=True)

Generate project structure tree content for index.ipynb

	Type	Default	Details
index_path	Path	None	Path to index.ipynb
marker	str	## Project Structure	Section marker
exclude_index	bool	True	Exclude index.ipynb from tree
Returns	str		Generated structure content

source

add_dependencies_section

 add_dependencies_section (index_path:pathlib.Path=None, marker:str='##
                           Module Dependencies', direction:str='LR')

Generate module dependencies diagram content for index.ipynb

	Type	Default	Details
index_path	Path	None	Path to index.ipynb
marker	str	## Module Dependencies	Section marker
direction	str	LR	Diagram direction
Returns	str		Generated dependencies content

source

add_cli_reference_section

 add_cli_reference_section (marker:str='## CLI Reference')

Generate CLI reference content for index.ipynb based on project’s console scripts

	Type	Default	Details
marker	str	## CLI Reference	Section marker
Returns	str		Generated CLI content

source

update_index_comprehensive

 update_index_comprehensive (index_path:pathlib.Path=None,
                             include_structure:bool=True,
                             include_dependencies:bool=True,
                             include_cli:bool=True,
                             include_modules:bool=True)

Comprehensively update index.ipynb with project structure, dependencies, CLI, and modules

	Type	Default	Details
index_path	Path	None	Path to index.ipynb
include_structure	bool	True	Include project structure
include_dependencies	bool	True	Include module dependencies
include_cli	bool	True	Include CLI reference
include_modules	bool	True	Include module documentation
Returns	None		Updates index.ipynb in place

# Example: Update index.ipynb with comprehensive documentation
# update_index_comprehensive()  # Full update with all sections

# Or customize what sections to include:
# update_index_comprehensive(
#     include_structure=True,     # Project tree
#     include_dependencies=True,  # Module dependencies 
#     include_cli=True,          # CLI reference
#     include_modules=True       # Module documentation
# )

Testing

Let’s test the API documentation generation on our project:

# First, let's export our modules
import nbdev
nbdev.nbdev_export()

# Test the updated generate_module_overview function
import nbdev
nbdev.nbdev_export()

# Test generating documentation for a single module
core_module = parse_notebook(Path("core.ipynb"))
print("Updated module overview with import statements:")
print("=" * 50)
print(generate_module_overview(core_module))

Updated module overview with import statements:
==================================================
### Core Utilities (`core.ipynb`)
> Core utilities and data models for nbdev project overview generation

#### Import

```python
# Import statements not available
```

#### Functions

```python
def get_notebook_files(path: Path = None,           # Directory to search (defaults to nbs_path)
                      recursive: bool = True        # Search subdirectories
                      ) -> List[Path]:              # List of notebook paths
    "Get all notebook files in a directory"
```

```python
def get_subdirectories(path: Path = None,           # Directory to search (defaults to nbs_path)
                      recursive: bool = False       # Include all nested subdirectories
                      ) -> List[Path]:              # List of directory paths
    "Get subdirectories in a directory"
```

```python
def read_notebook(path: Path                    # Path to notebook file
                 ) -> Dict[str, Any]:           # Notebook content as dict
    "Read a notebook file and return its content"
```

```python
def get_cell_source(cell: Dict[str, Any]        # Notebook cell
                   ) -> str:                    # Cell source as string
    "Get source from a notebook cell"
```

#### Classes

```python
@dataclass
class NotebookInfo:
    "Information about a single notebook"
    
    path: Path  # Path to the notebook file
    name: str  # Notebook filename without extension
    title: Optional[str]  # H1 title from first cell
    description: Optional[str]  # Blockquote description from first cell
    export_module: Optional[str]  # Module name from default_exp
    
    def relative_path(self) -> Path:       # Path relative to nbs directory
        "Get path relative to nbs directory"
```

```python
@dataclass
class DirectoryInfo:
    "Information about a directory in the nbs folder"
    
    path: Path  # Path to the directory
    name: str  # Directory name
    notebook_count: int = 0  # Number of notebooks in directory
    description: Optional[str]  # Description from folder's main notebook
    subdirs: List[DirectoryInfo] = field(...)  # Subdirectories
    notebooks: List[NotebookInfo] = field(...)  # Notebooks in this directory
    
    def total_notebook_count(self) -> int:          # Total notebooks including subdirs
        "Get total notebook count including subdirectories"
```

# Test another module to see how the imports look
parsers_module = parse_notebook(Path("parsers.ipynb"))
print("Parsers module overview:")
print("=" * 30)
print(generate_module_overview(parsers_module)[:800] + "..." if len(generate_module_overview(parsers_module)) > 800 else generate_module_overview(parsers_module))

Parsers module overview:
==============================
### Notebook and Module Parsing (`parsers.ipynb`)
> Parse notebook metadata, content, and extract function/class signatures with docments

#### Import

```python
# Import statements not available
```

#### Functions

```python
def extract_docments_signature(node: ast.FunctionDef,          # AST function node
                              source_lines: List[str]          # Source code lines
                              ) -> str:                        # Function signature
    "Extract function signature with docments-style comments"
```

```python
def _parse_decorators(node: Union[ast.ClassDef, ast.FunctionDef]  # AST node with decorators
                     ) -> List[str]:                              # List of decorator names
    "Parse decorators from an AST node"
```

```python
def pa...