Coverage for picos/apidoc.py: 80.00%
15 statements
« prev ^ index » next coverage.py v6.5.0, created at 2023-02-15 14:21 +0000
« prev ^ index » next coverage.py v6.5.0, created at 2023-02-15 14:21 +0000
1# ------------------------------------------------------------------------------
2# Copyright (C) 2019 Maximilian Stahlberg
3#
4# This file is part of PICOS.
5#
6# PICOS is free software: you can redistribute it and/or modify it under the
7# terms of the GNU General Public License as published by the Free Software
8# Foundation, either version 3 of the License, or (at your option) any later
9# version.
10#
11# PICOS is distributed in the hope that it will be useful, but WITHOUT ANY
12# WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
13# A PARTICULAR PURPOSE. See the GNU General Public License for more details.
14#
15# You should have received a copy of the GNU General Public License along with
16# this program. If not, see <http://www.gnu.org/licenses/>.
17# ------------------------------------------------------------------------------
19"""Functions to support the automatic API documentation.
21The environment variable ``PICOS_WARN_MISSING_DOCSTRINGS`` can be set to warn
22about missing docstrings for top level objects of a module.
23"""
25import warnings
26from types import ModuleType
28_API_START = set(globals()) # api_start is not yet defined.
29# -------------------------
32def api_start(theGlobals):
33 """Mark the start of a module's content.
35 Store the returned value and pass it to :func:`api_end`.
36 """
37 return set(theGlobals)
40def api_end(startGlobals, endGlobals):
41 """Mark the end of a module's content.
43 Store the returned value in __all__.
44 """
45 names = sorted(set(name for name, obj in endGlobals.items()
46 if not name.startswith("_") and not isinstance(obj, ModuleType))
47 .difference(startGlobals))
49 from . import settings
51 if settings.WARN_MISSING_DOCSTRINGS:
52 for name in names:
53 if not endGlobals[name].__doc__:
54 warnings.warn(
55 "Top level object {}.{} has empty docstring."
56 .format(endGlobals["__name__"], name), stacklevel=3)
58 return names
61# --------------------------------------
62__all__ = api_end(_API_START, globals())