Source code for picos.apidoc

# coding: utf-8

# ------------------------------------------------------------------------------
# Copyright (C) 2019 Maximilian Stahlberg
#
# This file is part of PICOS.
#
# PICOS is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# PICOS is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.
# ------------------------------------------------------------------------------

"""Functions to support the automatic API documentation.

The environment variable ``PICOS_WARN_MISSING_DOCSTRINGS`` can be set to warn
about missing docstrings for top level objects of a module.
"""

import os
import warnings
from types import ModuleType


_API_START = set(globals())  # api_start is not yet defined.
# -------------------------


[docs]def api_start(theGlobals): """Mark the start of a module's content. Store the returned value and pass it to :func:`api_end`. """ return set(theGlobals)
[docs]def api_end(startGlobals, endGlobals): """Mark the end of a module's content. Store the returned value in __all__. """ names = sorted(set(name for name, obj in endGlobals.items() if not name.startswith("_") and not isinstance(obj, ModuleType)) .difference(startGlobals)) if "PICOS_WARN_MISSING_DOCSTRINGS" in os.environ: for name in names: if not endGlobals[name].__doc__: warnings.warn( "Top level object {}.{} has empty docstring." .format(endGlobals["__name__"], name), stacklevel=3) return names
# -------------------------------------- __all__ = api_end(_API_START, globals())