Skip to content

Standardise Your Documentation with Configuration🔗

Define your own standards and ensure consistency across your project with a pyproject.toml file. docstring-format-checker (or dfc) offers a wide range of configuration options to suit any project's needs.

🌍 Global Configuration Options🔗

Configuring these options at the top-level of the [tool.dfc] section affects how dfc behaves across all checked files.

There are five main global options you can set.

1. Require Docstring🔗

Enforce documentation across your entire project by setting require_docstrings to true.

Config Type Required Default
require_docstrings boolean no true

When enabled, dfc flags any public function, method, or class that lacks a docstring.

Option Description
true dfc will report missing docstrings as errors.
false dfc will not report missing docstrings as errors.
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

2. Check Private Members🔗

By default, dfc only checks public members (those that do not start with an underscore _).

Config Type Required Default
check_private boolean no false

Set check_private to true to include private functions and methods in the checks.

Option Description
true dfc will check both public and private members.
false dfc will only check public members.
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

3. Allow Undefined Sections🔗

Control how dfc handles sections that are not explicitly defined in your configuration.

Config Type Required Default
allow_undefined_sections boolean no false

If set to false, any section header found in a docstring that does not match a defined section name raises an error.

Option Description
true dfc will ignore any undefined sections.
false dfc will report undefined sections as errors.
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

4. Validate Parameter Types🔗

Ensure that all parameters in your Params (or similar) section include type annotations.

Config Type Required Default
validate_param_types boolean no true

When true, dfc expects the format name (type): description.

Option Description
true dfc will validate that each parameter has a type specified.
false dfc will not check for parameter types.
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

5. Optional Style🔗

Standardise how optional parameters are described.

Config Type Required Default
optional_style string no "validate"

This setting controls how dfc reports issues when a parameter has a default value in the function signature.

Option Description
"silent" Do not report any missing optional indicator.
"validate" Warn if , optional is present but the parameter does not have a default value.
"strict" Require all parameters with default value to include the , optional suffix in the docstring.
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

📂 Section Configuration🔗

Define specific sections within your docstrings using the [[tool.dfc.sections]] array. This allows you to validate for summaries, parameters, return values, and more.

There are seven section options you can set.

1. Section Name🔗

Specify the name of the section as it appears in your docstrings.

Config Type Required Default
name string yes required

dfc looks for this exact string (case-insensitive) followed by a colon.

pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

2. Section Type🔗

Define the expected format of the section content.

Config Type Required Default
type string yes required

Each type has specific validation rules.

Option Description Example
"free_text" Any text content. Summary, Notes
"list_name" A list of named items. See Also
"list_type" A list of types. Raises
"list_name_and_type" A list of names with types in parentheses. Params, Returns
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

3. Order🔗

Enforce a specific sequence of sections within your docstrings.

Config Type Required Default
order integer no null

If two sections have an order defined, dfc ensures they appear in that relative order. If order is not set, the section can appear anywhere in the docstring. If order is set, all sections with an order must appear before any sections without an order, maintaining the defined sequence, and cannot have any duplicate order values.

pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

4. Admonitions🔗

Standardise modern documentation styles like MkDocs-Material admonitions.

Config Type Required Default
admonition string or boolean no false

If you provide an admonition type (like "note" or "info"), you must also provide a prefix (like "!!!" or "???"). dfc will then expect the section to be formatted as an admonition: !!! note "Section Name".

For more details on supported admonition types, see the MkDocs-Material documentation.

pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

5. Prefix🔗

Specify the prefix used for admonitions.

Config Type Required Default
prefix string yes if admonition is set, otherwise no ""

If you set an admonition type, you must also provide a prefix to indicate how the admonition is formatted.

Option Description
!!! Standard admonition section.
??? Expandable admonition section, not expanded.
???+ Expandable admonition section, expanded by default.

For more details on supported prefixes, see the MkDocs-Material documentation.

pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

6. Required🔗

Mark a section as mandatory for every docstring.

Config Type Required Default
required boolean no false
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

7. Custom Error Message🔗

Provide a more helpful error message when a section validator fails or a required section is missing.

Config Type Required Default
message string no ""
pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
[tool.dfc]
require_docstrings = true
check_private = true
allow_undefined_sections = false
validate_param_types = true
optional_style = "validate"

[[tool.dfc.sections]]
name = "summary"
type = "free_text"
order = 1
admonition = "note"
required = true
prefix = "!!!"
message = "A brief summary is required."

[[tool.dfc.sections]]
name = "details"
type = "free_text"
order = 2
required = false
admonition = "abstract"
prefix = "???+"

[[tool.dfc.sections]]
name = "params"
type = "list_name_and_type"
order = 3
required = false

[[tool.dfc.sections]]
name = "raises"
type = "list_type"
order = 4
required = false

[[tool.dfc.sections]]
name = "notes"
type = "free_text"
admonition = "note"
prefix = "???"

🛠️ How To: Customise Your Config🔗

Walk through a practical example to see how these options work together.

Create a sample module🔗

Create sample_config.py to test different configurations:

sample_config.py
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
def my_function(param1: int, param2: str = "default") -> bool:
    """
    !!! note "Summary"
        This is a function with a summary in an admonition.

    Params:
        param1 (int): The first parameter.
        param2 (str): The second parameter.

    Returns:
        (bool): Success or failure.
    """
    return True


def _private_function():
    """
    This is a private function.
    """
    pass


def undocumented_function():
    pass

Use Global Flags🔗

Apply global settings to control the tool's overall behaviour. Create pyproject.toml:

pyproject.toml
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
[tool.dfc]
# Require docstrings for all functions/methods (default: true)
require_docstrings = true

# Check private members starting with an underscore (default: false)
check_private = true

# Allow sections that are not defined in the configuration (default: false)
allow_undefined_sections = true

# Validate that parameter types are provided (default: true)
validate_param_types = true

# Style for reporting issues in optional sections (silent, validate, strict)
optional_style = "strict"

Run dfc with this configuration:

Terminal
1
dfc --config=pyproject.toml sample_config.py

docs/usage/sample_config.py
  Line 1 - function 'my_function':
    - Parameter 'param2' has default value but missing ', optional' suffix in docstring
  Line 15 - function '_private_function':
    - Missing required section: 'summary'
  Line 21 - function 'undocumented_function':
    - Missing docstring for function

Found 3 error(s) in 3 functions over 1 file

Notice how dfc now checks private functions and enforces strict optional parameter naming.

Design Custom Sections🔗

Define your own documentation structure. Create pyproject.toml:

pyproject.toml
1
2
3
4
5
6
7
[tool.dfc]
require_docstrings = true
sections = [
    { order = 1, name = "summary", type = "free_text", required = true, admonition = "note", prefix = "!!!" },
    { order = 2, name = "params", type = "list_name_and_type", required = true },
    { order = 3, name = "returns", type = "list_name_and_type", required = false, message = "Please include what this function returns." },
]

Run the check again:

Terminal
1
dfc --config=pyproject.toml sample_config.py

docs/usage/sample_config.py
  Line 21 - function 'undocumented_function':
    - Missing docstring for function

Found 1 error(s) in 1 function over 1 file

In this case, my_function() and _private_function() pass because they meet the basic requirements of the new section config, while undocumented_function() still fails because docstrings are required globally.

💡 Watch-outs and Pro-tips🔗

Watch-out: Duplicate Orders🔗

Never assign the same order value to two different sections. If you do, dfc will raise an InvalidConfigError_DuplicateOrderValues and stop execution.

Pro-tip: Floating Sections🔗

Omit the order attribute for sections that might appear anywhere, such as "Notes" or "Examples". These are referred to as "floating" sections. They provide flexibility while still ensuring the content follows your mandated type.

Pro-tip: Disable Built-ins🔗

If you provide a sections list in your pyproject.toml, dfc completely replaces the default configuration. This allows you to fully customise what sections are checked without any unexpected behavior from built-in defaults.

🔍 Configuration Discovery🔗

dfc automatically looks for configuration in the following order:

  1. A path provided via the --config or -f command-line argument.
  2. A pyproject.toml file in the current working directory containing a [tool.dfc] or [tool.docstring-format-checker] section.
  3. The default built-in configuration if no file is found.