[Python-modules-commits] [sphinx-celery] 03/04: New builder configcheck replaces verify_config_reference
Christopher Stuart Hoskin
mans0954 at moszumanska.debian.org
Fri Aug 18 07:00:22 UTC 2017
This is an automated email from the git hooks/post-receive script.
mans0954 pushed a commit to tag v1.1.0
in repository sphinx-celery.
commit 3e00337c2864c896cb692319c34916d5ae68bd12
Author: Ask Solem <ask at celeryproject.org>
Date: Fri Apr 8 16:12:40 2016 -0700
New builder configcheck replaces verify_config_reference
---
sphinx_celery/apicheck.py | 32 ++--------
sphinx_celery/builders.py | 33 ++++++++++
sphinx_celery/conf.py | 1 +
sphinx_celery/configcheck.py | 139 +++++++++++++++++++++++++++++++++++++++++++
4 files changed, 177 insertions(+), 28 deletions(-)
diff --git a/sphinx_celery/apicheck.py b/sphinx_celery/apicheck.py
index 0d1acf5..e47e70c 100644
--- a/sphinx_celery/apicheck.py
+++ b/sphinx_celery/apicheck.py
@@ -59,16 +59,14 @@ from __future__ import absolute_import, unicode_literals
import importlib
import os
-import pickle
-import re
from collections import defaultdict
from six import string_types
-from sphinx.builders import Builder
from sphinx.ext import autodoc
from sphinx.util.console import bold, darkgreen, green, red
+from .builders import BaseBuilder
from .utils import bytes_if_py2
DEFAULT_IGNORE = [r'.*?\.tests.*']
@@ -79,8 +77,6 @@ SUBHEADER = '-'
ERR = 'ERROR'
ERR_MISSING = '{error}: In index but module does not exist: {module}'
ERR_UNDOCUMENTED = 'Undocumented Autodoc Modules'
-ERR_INVALID_REGEX = 'Invalid regex {0!r} in apicheck_ignore_modules: {1!r}'
-
OK_STATUS = 'OK: All modules documented :o)'
NOK_STATUS = """
@@ -139,9 +135,10 @@ def find_python_modules(package):
yield '.'.join([package, filename])[:-3]
-class APICheckBuilder(Builder):
+class APICheckBuilder(BaseBuilder):
name = 'apicheck'
+ pickle_filename = 'apicheck.pickle'
find_modules = {
'py': find_python_modules,
@@ -158,22 +155,6 @@ class APICheckBuilder(Builder):
self.undocumented = defaultdict(list)
self.all_modules = defaultdict(set)
- def compile_regex(self, regex):
- if not regex.startswith('^'):
- regex = '^{0}'.format(regex)
- if not regex.endswith('$'):
- regex = '{0}$'.format(regex)
- try:
- return re.compile(regex)
- except Exception as exc:
- self.warn(ERR_INVALID_REGEX.format(regex, exc))
-
- def compile_regexes(self, regexes):
- return [self.compile_regex(regex) for regex in regexes]
-
- def get_outdated_docs(self):
- return 'apicheck overview'
-
def is_ignored_module(self, module):
return any(regex.match(module) for regex in self.ignore_patterns)
@@ -236,16 +217,11 @@ class APICheckBuilder(Builder):
'undocumented': dict(self.undocumented),
}
- def finish(self):
- picklepath = os.path.join(self.outdir, 'apicheck.pickle')
- with open(picklepath, mode='wb') as fh:
- pickle.dump(self.as_dict(), fh)
-
def setup(app):
app.add_builder(APICheckBuilder)
app.add_config_value(
- bytes_if_py2('apicheck_ignore_modules'), [".*?\.tests.*"], False)
+ bytes_if_py2('apicheck_ignore_modules'), [], False)
app.add_config_value(
bytes_if_py2('apicheck_domains'), ['py'], False)
app.add_config_value(
diff --git a/sphinx_celery/builders.py b/sphinx_celery/builders.py
new file mode 100644
index 0000000..a8c666c
--- /dev/null
+++ b/sphinx_celery/builders.py
@@ -0,0 +1,33 @@
+from __future__ import absolute_import, unicode_literals
+
+import os
+import pickle
+import re
+
+from sphinx.builders import Builder
+
+ERR_INVALID_REGEX = 'Invalid regex {0!r} in apicheck_ignore_modules: {1!r}'
+
+
+class BaseBuilder(Builder):
+
+ def get_outdated_docs(self):
+ return '{0} overview'.format(self.name)
+
+ def finish(self):
+ picklepath = os.path.join(self.outdir, self.pickle_filename)
+ with open(picklepath, mode='wb') as fh:
+ pickle.dump(self.as_dict(), fh)
+
+ def compile_regex(self, regex):
+ if not regex.startswith('^'):
+ regex = '^{0}'.format(regex)
+ if not regex.endswith('$'):
+ regex = '{0}$'.format(regex)
+ try:
+ return re.compile(regex)
+ except Exception as exc:
+ self.warn(ERR_INVALID_REGEX.format(regex, exc))
+
+ def compile_regexes(self, regexes):
+ return [self.compile_regex(regex) for regex in regexes]
diff --git a/sphinx_celery/conf.py b/sphinx_celery/conf.py
index ed353a9..793fdb9 100644
--- a/sphinx_celery/conf.py
+++ b/sphinx_celery/conf.py
@@ -26,6 +26,7 @@ EXTENSIONS = [
'sphinx_celery.signal_crossref',
'sphinx_celery.setting_crossref',
'sphinx_celery.apicheck',
+ 'sphinx_celery.configcheck',
]
INTERSPHINX_MAPPING = {
diff --git a/sphinx_celery/configcheck.py b/sphinx_celery/configcheck.py
new file mode 100644
index 0000000..ac68ae3
--- /dev/null
+++ b/sphinx_celery/configcheck.py
@@ -0,0 +1,139 @@
+"""
+
+Sphinx Configuration Reference Checker
+======================================
+
+This builder extension makes sure all settings in the documented
+package are represented in the configuration reference (
+meaning they all have ``.. setting::`` directives).
+
+Usage
+-----
+
+.. code-block:: console
+
+ $ sphinx-build -b configcheck -d _build/doctrees . _build/configcheck
+
+Configuration
+-------------
+
+configcheck_ignore_settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+List of settings to ignore, either as setting names or regexes.
+
+Example:
+
+.. code-block:: python
+
+ configcheck_ignore_settings = [
+ 'USE_TZ',
+ r'.*SECRET.*',
+ ]
+
+configcheck_project_settings
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A function returning a set of all setting names.
+
+Example:
+
+.. code-block:: python
+
+ def configcheck_project_settings():
+ from django import conf
+
+ return set(conf._all_settings)
+
+
+configcheck_should_ignore
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Optional function that can be used in addition to
+``configcheck_ignore_settings`` to ignore setting names programmatically.
+
+
+Example:
+
+.. code-block:: python
+
+ def configcheck_should_ignore(setting):
+ from django import conf
+ return conf.is_deprecated(setting)
+
+
+"""
+from __future__ import absolute_import, unicode_literals
+
+from six import iterkeys as keys
+
+from sphinx.util.console import bold, green, red
+
+from .builders import BaseBuilder
+from .utils import bytes_if_py2
+
+ERR = 'ERROR'
+ERR_MISSING_DOC = '{error}: Setting not documented: {name}'
+OK_STATUS = 'OK: All settings documented :o)'
+
+
+class ConfigCheckBuilder(BaseBuilder):
+
+ name = 'configcheck'
+ pickle_filename = 'configcheck.pickle'
+
+ def init(self):
+ self.ignore_patterns = self.compile_regexes(
+ self.config.configcheck_ignore_settings,
+ )
+ self.should_ignore = (
+ self.config.configcheck_should_ignore or (lambda s: False))
+ print(self.should_ignore)
+ self.project_settings = self.config.configcheck_project_settings
+ self.undocumented = set()
+
+ def is_ignored_setting(self, setting):
+ return self.should_ignore(setting) or any(
+ regex.match(setting) for regex in self.ignore_patterns)
+
+ def write(self, *ignored):
+ self.check_missing()
+
+ def documented_settings(self):
+ return {
+ name for reftype, name in keys(
+ self.app.env.domaindata['std']['objects'])
+ if reftype == 'setting'
+ }
+
+ def check_missing(self):
+ all_settings = self.project_settings()
+ documented_settings = self.documented_settings()
+ self.undocumented.update(
+ setting for setting in all_settings ^ documented_settings
+ if not self.is_ignored_setting(setting)
+ )
+
+ for setting in self.undocumented:
+ self.app.statuscode = 2
+ print(ERR_MISSING_DOC.format(
+ error=red(ERR),
+ name=bold(setting),
+ ))
+ if not self.app.statuscode:
+ print(green(OK_STATUS))
+
+ def as_dict(self):
+ return {
+ 'undocumented': self.undocumented,
+ }
+
+
+def setup(app):
+ app.add_builder(ConfigCheckBuilder)
+ app.add_config_value(
+ bytes_if_py2('configcheck_ignore_settings'), [], False)
+ app.add_config_value(
+ bytes_if_py2('configcheck_project_settings'), None, False)
+ app.add_config_value(
+ bytes_if_py2('configcheck_should_ignore'), None, False)
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/sphinx-celery.git
More information about the Python-modules-commits
mailing list