# 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"))API Documentation Generation
Generate module overviews with formatted signatures for nbdev projects
Formatting Functions
format_function_doc
def format_function_doc(
func:FunctionInfo, # Function information
indent:str='', # Indentation prefix
)->str: # Formatted documentation
Format a function with its signature for documentation
format_class_doc
def format_class_doc(
cls:ClassInfo, # Class information
)->str: # Formatted documentation
Format a class with its signature and methods for documentation
format_variable_doc
def format_variable_doc(
var:VariableInfo, # Variable information
)->str: # Formatted documentation
Format a variable for documentation
Module Documentation Generation
generate_module_overview
def generate_module_overview(
module:ModuleInfo, # Module information
show_all:bool=False, # Show all items including private
)->str: # Module overview markdown
Generate a markdown overview for a module
generate_project_api_docs
def generate_project_api_docs(
path:Path=None, # Project path (defaults to nbs_path)
show_all:bool=False, # Show all items including private
)->str: # Full API documentation
Generate API documentation for all modules in a project
Index Update Function
The update_index_module_docs function can automatically update your project’s index.ipynb with module documentation:
update_index_module_docs
def update_index_module_docs(
index_path:Path=None, # Path to index.ipynb (defaults to nbs/index.ipynb)
start_marker:str='## Module Overview', # Marker to identify module docs section
)->None: # Updates index.ipynb in place
Update the module documentation section in index.ipynb
Comprehensive Index Update Functions
Additional functions to update index.ipynb with project structure, dependencies, CLI reference, and statistics:
add_project_structure_section
def add_project_structure_section(
index_path:Path=None, # Path to index.ipynb
marker:str='## Project Structure', # Section marker
exclude_index:bool=True, # Exclude index.ipynb from tree
)->str: # Generated structure content
Generate project structure tree content for index.ipynb
add_dependencies_section
def add_dependencies_section(
index_path:Path=None, # Path to index.ipynb
marker:str='## Module Dependencies', # Section marker
direction:str='LR', # Diagram direction
)->str: # Generated dependencies content
Generate module dependencies diagram content for index.ipynb
add_cli_reference_section
def add_cli_reference_section(
marker:str='## CLI Reference', # Section marker
)->str: # Generated CLI content
Generate CLI reference content for index.ipynb based on project’s console scripts
update_index_comprehensive
def update_index_comprehensive(
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
)->None: # Updates index.ipynb in place
Comprehensively update index.ipynb with project structure, dependencies, CLI, and modules
# 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...