42 lines
988 B
Python
42 lines
988 B
Python
# SPDX-FileCopyrightText: 2024 Thomas Touhey
|
|
# SPDX-License-Identifier: GPL-3.0-only
|
|
"""Sphinx extension to remove the first line from module docstrings."""
|
|
|
|
from __future__ import annotations
|
|
|
|
from typing import TYPE_CHECKING, Any
|
|
|
|
if TYPE_CHECKING:
|
|
from sphinx.application import Sphinx
|
|
|
|
|
|
def remove_first_line_in_module_docstring(
|
|
_app: Sphinx,
|
|
what: str,
|
|
_name: str,
|
|
_obj: Any,
|
|
_options: Any,
|
|
lines: list[str],
|
|
) -> None:
|
|
"""Remove the first line from the docstring.
|
|
|
|
This is because the first line of the docstring is summed up in the
|
|
document title, before the module autodoc.
|
|
"""
|
|
if what != "module" or not lines:
|
|
return
|
|
|
|
for i in range(1, len(lines)):
|
|
if not lines[i]:
|
|
lines[: i + 1] = []
|
|
return
|
|
|
|
lines[:] = []
|
|
|
|
|
|
def setup(app: Sphinx) -> None:
|
|
"""Set up the extension."""
|
|
app.connect(
|
|
"autodoc-process-docstring",
|
|
remove_first_line_in_module_docstring,
|
|
)
|