Docs

Docs#

Documentation utilities for Nabla.

This module provides decorators and utilities for controlling documentation generation.

nabla.utils.docs.nodoc(obj)[source]#

Decorator to mark functions, methods, or classes as non-documentable.

This decorator adds a special attribute to the decorated object that can be checked by documentation generation tools to exclude it from generated docs.

Parameters:

obj (F | C) – The function, method, or class to mark as non-documentable.

Returns:

The original object with the _nabla_nodoc attribute set to True.

Return type:

F | C

Examples

>>> @nodoc
... def internal_helper():
...     '''This function won't appear in generated docs.'''
...     pass

>>> @nodoc
... class InternalClass:
...     '''This class won't appear in generated docs.'''
...     pass
nabla.utils.docs.is_documentable(obj)[source]#

Check if an object should be included in documentation.

Parameters:

obj (Any) – The object to check.

Returns:

False if the object is marked with @nodoc, True otherwise.

Return type:

bool

nabla.utils.docs.should_document(obj, name)[source]#

Determine if an object should be documented based on various criteria.

This function checks: 1. If the object is marked with @nodoc decorator 2. If the name starts with underscore (private/internal) 3. Other standard exclusion criteria

Parameters:

  • obj (Any) – The object to check.

  • name (str) – The name of the object.

Returns:

True if the object should be documented, False otherwise.

Return type:

bool

nabla.utils.docs.no_doc(obj)#

Decorator to mark functions, methods, or classes as non-documentable.

This decorator adds a special attribute to the decorated object that can be checked by documentation generation tools to exclude it from generated docs.

Parameters:

obj (F | C) – The function, method, or class to mark as non-documentable.

Returns:

The original object with the _nabla_nodoc attribute set to True.

Return type:

F | C

Examples

>>> @nodoc
... def internal_helper():
...     '''This function won't appear in generated docs.'''
...     pass

>>> @nodoc
... class InternalClass:
...     '''This class won't appear in generated docs.'''
...     pass
nabla.utils.docs.skip_doc(obj)#

Decorator to mark functions, methods, or classes as non-documentable.

This decorator adds a special attribute to the decorated object that can be checked by documentation generation tools to exclude it from generated docs.

Parameters:

obj (F | C) – The function, method, or class to mark as non-documentable.

Returns:

The original object with the _nabla_nodoc attribute set to True.

Return type:

F | C

Examples

>>> @nodoc
... def internal_helper():
...     '''This function won't appear in generated docs.'''
...     pass

>>> @nodoc
... class InternalClass:
...     '''This class won't appear in generated docs.'''
...     pass
Contents