From b835543f65a23c76224c9558bbda0a19f3be938d Mon Sep 17 00:00:00 2001 From: Brian Curtin Date: Wed, 5 Apr 2017 10:37:47 -0400 Subject: [PATCH] Enable warnings_as_errors in doc enforcer Rather than occasionally playing catch-up until the wait_for methods are removed from the base Proxy in 1.0, we can temporarily ignore those two names. This allows us to make the doc build fail if undocumented proxy methods occur. After 1.0 we should remove the special cases for wait_for names, but leave warnings_as_errors on. Change-Id: I8fe41ed639ec318a18db3022371b52382c53aa99 --- doc/source/conf.py | 2 +- doc/source/enforcer.py | 26 +++++++++++++++++++++++++- 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/doc/source/conf.py b/doc/source/conf.py index 8dee8f737..6c4cbcf16 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -30,7 +30,7 @@ extensions = [ ] # When True, this will raise an exception that kills sphinx-build. -enforcer_warnings_as_errors = False +enforcer_warnings_as_errors = True # autodoc generation is a bit aggressive and a nuisance when doing heavy # text edit cycles. diff --git a/doc/source/enforcer.py b/doc/source/enforcer.py index f75f9a307..8f653b099 100644 --- a/doc/source/enforcer.py +++ b/doc/source/enforcer.py @@ -1,4 +1,5 @@ import importlib +import itertools import os from bs4 import BeautifulSoup @@ -10,6 +11,13 @@ DEBUG = True if os.getenv("ENFORCER_DEBUG") else False WRITTEN_METHODS = set() +# NOTE: This is temporary! These methods currently exist on the base +# Proxy class as public methods, but they're deprecated in favor of +# subclasses actually exposing them if necessary. However, as they're +# public and purposely undocumented, they cause spurious warnings. +# Ignore these methods until they're actually removed from the API, +# and then we can take this special case out. +IGNORED_METHODS = ("wait_for_delete", "wait_for_status") class EnforcementError(errors.SphinxError): """A mismatch between what exists and what's documented""" @@ -47,6 +55,11 @@ def get_proxy_methods(): instance = module.Proxy("") # We only document public names names = [name for name in dir(instance) if not name.startswith("_")] + + # Remove the wait_for_* names temporarily. + for name in IGNORED_METHODS: + names.remove(name) + good_names = [module.__name__ + ".Proxy." + name for name in names] methods.update(good_names) @@ -94,6 +107,17 @@ def build_finished(app, exception): app.info("ENFORCER: %d proxy methods exist" % len(all_methods)) app.info("ENFORCER: %d proxy methods written" % len(WRITTEN_METHODS)) missing = all_methods - WRITTEN_METHODS + + def is_ignored(name): + for ignored_name in IGNORED_METHODS: + if ignored_name in name: + return True + return False + + # TEMPORARY: Ignore the wait_for names when determining what is missing. + app.info("ENFORCER: Ignoring wait_for_* names...") + missing = set(itertools.ifilterfalse(is_ignored, missing)) + missing_count = len(missing) app.info("ENFORCER: Found %d missing proxy methods " "in the output" % missing_count) @@ -101,7 +125,7 @@ def build_finished(app, exception): for name in sorted(missing): app.warn("ENFORCER: %s was not included in the output" % name) - if app.config.enforcer_warnings_as_errors: + if app.config.enforcer_warnings_as_errors and missing_count > 0: raise EnforcementError( "There are %d undocumented proxy methods" % missing_count)