Skip to content

configuration.md

Latest commit

 

History

History
99 lines (64 loc) · 2.9 KB

configuration.md

File metadata and controls

99 lines (64 loc) · 2.9 KB

Configuration files

Docstub will automatically look for configuration files in the current directory. These files must be named

  • pyproject.toml
  • docstub.toml

Alternatively, config files can also be passed in the command line with the --config option. In this case, docstub will not look for configuration files in the current directory. When multiple configuration files are passed explicitly, their content is merged.

Out of the box, docstub makes use of an internal configuration files are always loaded. One such file is numpy_config.toml which provides defaults for NumPy types.

Configuration fields in [tool.docstub]

All configuration must be declared inside a [tool.docstub] table.

ignore_files

TOML type: array of string(s)

Ignore files and directories matching these glob-style patterns. Patterns that don't start with "/" are interpreted as relative to the directory that contains the Python package for which stubs are generated.

Example:

[tool.docstub]
ignore_files = [
    "**/tests",
]
  • Will ignore any directory anywhere that is named tests.

types

TOML type: table, mapping string to string

Types and their external modules to use in docstrings. Docstub can't yet automatically discover where to import types from other packages from. Instead, you can provide this information explicitly. Any type on the left side will be associated with the given "module" on the right side.

Example:

[tool.docstub.types]
Path = "pathlib"
NDArray = "numpy.typing"
  • Will allow using Path in docstrings and will use from pathlib import Path to import the type.
  • Will allow using NDarray in docstrings and will use from numpy.typing import NDArray to import the type.

type_prefixes

TOML type: table, mapping string to string

Prefixes for external modules to match types in docstrings. Docstub can't yet automatically discover where to import types from other packages from. Instead, you can provide this information explicitly. Any type in a docstring whose prefix matches the name given on the left side, will be associated with the given "module" on the right side.

Example:

[tool.docstub.type_prefixes]
np = "numpy"
plt = "matplotlib.pyplot
  • Will match np.uint8 and np.typing.NDarray and use import numpy as np.
  • Will match plt.Figure use import matplotlib.pyplot as plt.

type_nicknames

TOML type: table, mapping string to string

Nicknames for types that can be used in docstrings to describe valid Python types or annotations.

Example:

[tool.docstub.type_nicknames]
func = "Callable"
buffer = "collections.abc.Buffer"
  • Will map func to the Callable.
  • Will map buffer to collections.abc.Buffer.