Coverage for picos/apidoc.py: 80.00%

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# ------------------------------------------------------------------------------ 

18 

19"""Functions to support the automatic API documentation. 

20 

21The environment variable ``PICOS_WARN_MISSING_DOCSTRINGS`` can be set to warn 

22about missing docstrings for top level objects of a module. 

23""" 

24 

25import warnings 

26from types import ModuleType 

27 

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

29# ------------------------- 

30 

31 

32def api_start(theGlobals): 

33 """Mark the start of a module's content. 

34 

35 Store the returned value and pass it to :func:`api_end`. 

36 """ 

37 return set(theGlobals) 

38 

39 

40def api_end(startGlobals, endGlobals): 

41 """Mark the end of a module's content. 

42 

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)) 

48 

49 from . import settings 

50 

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) 

57 

58 return names 

59 

60 

61# -------------------------------------- 

62__all__ = api_end(_API_START, globals())