def sites(c):
"""
Build both doc sites w/ maxed nitpicking.
"""
# TODO: This is super lolzy but we haven't actually tackled nontrivial
# in-Python task calling yet, so we do this to get a copy of 'our' context,
# which has been updated with the per-collection config data of the
# docs/www subcollections.
docs_c = Context(config=c.config.clone())
www_c = Context(config=c.config.clone())
docs_c.update(**docs.configuration())
www_c.update(**www.configuration())
# Must build both normally first to ensure good intersphinx inventory files
# exist =/ circular dependencies ahoy! Do it quietly to avoid pulluting
# output; only super-serious errors will bubble up.
# TODO: wants a 'temporarily tweak context settings' contextmanager
# TODO: also a f*****g spinner cuz this confuses me every time I run it
# when the docs aren't already prebuilt
docs_c["run"].hide = True
www_c["run"].hide = True
docs["build"](docs_c)
www["build"](www_c)
docs_c["run"].hide = False
www_c["run"].hide = False
# Run the actual builds, with nitpick=True (nitpicks + tracebacks)
docs["build"](docs_c, nitpick=True)
www["build"](www_c, nitpick=True)
def watch_docs(c):
"""
Watch both doc trees & rebuild them if files change.
This includes e.g. rebuilding the API docs if the source code changes;
rebuilding the WWW docs if the README changes; etc.
Reuses the configuration values ``packaging.package`` or ``tests.package``
(the former winning over the latter if both defined) when determining which
source directory to scan for API doc updates.
"""
# TODO: break back down into generic single-site version, then create split
# tasks as with docs/www above. Probably wants raft#63.
# NOTE: 'www'/'docs' refer to the module level sub-collections. meh.
# Readme & WWW triggers WWW
www_c = Context(config=c.config.clone())
www_c.update(**www.configuration())
www_handler = make_handler(
ctx=www_c,
task_=www["build"],
regexes=[r"\./README.rst", r"\./sites/www"],
ignore_regexes=[r".*/\..*\.swp", r"\./sites/www/_build"],
)
# Code and docs trigger API
docs_c = Context(config=c.config.clone())
docs_c.update(**docs.configuration())
regexes = [r"\./sites/docs"]
package = c.get("packaging", {}).get("package", None)
if package is None:
package = c.get("tests", {}).get("package", None)
if package:
regexes.append(r"\./{}/".format(package))
api_handler = make_handler(
ctx=docs_c,
task_=docs["build"],
regexes=regexes,
ignore_regexes=[r".*/\..*\.swp", r"\./sites/docs/_build"],
)
observe(www_handler, api_handler)
class configuration_proxy:
"Dict-like proxy for self.config"
def setup(self):
config = Config(defaults={"foo": "bar", "biz": {"baz": "boz"}})
self.c = Context(config=config)
def direct_access_allowed(self):
assert self.c.config.__class__ == Config
assert self.c.config["foo"] == "bar"
assert self.c.config.foo == "bar"
def config_attr_may_be_overwritten_at_runtime(self):
new_config = Config(defaults={"foo": "notbar"})
self.c.config = new_config
assert self.c.foo == "notbar"
def getitem(self):
"___getitem__"
assert self.c["foo"] == "bar"
assert self.c["biz"]["baz"] == "boz"
def getattr(self):
"__getattr__"
assert self.c.foo == "bar"
assert self.c.biz.baz == "boz"
def get(self):
assert self.c.get("foo") == "bar"
assert self.c.get("nope", "wut") == "wut"
assert self.c.biz.get("nope", "hrm") == "hrm"
def pop(self):
assert self.c.pop("foo") == "bar"
assert self.c.pop("foo", "notbar") == "notbar"
assert self.c.biz.pop("baz") == "boz"
def popitem(self):
assert self.c.biz.popitem() == ("baz", "boz")
del self.c["biz"]
assert self.c.popitem() == ("foo", "bar")
assert self.c.config == {}
def del_(self):
"del"
del self.c["foo"]
del self.c["biz"]["baz"]
assert self.c.biz == {}
del self.c["biz"]
assert self.c.config == {}
def clear(self):
self.c.biz.clear()
assert self.c.biz == {}
self.c.clear()
assert self.c.config == {}
def setdefault(self):
assert self.c.setdefault("foo") == "bar"
assert self.c.biz.setdefault("baz") == "boz"
assert self.c.setdefault("notfoo", "notbar") == "notbar"
assert self.c.notfoo == "notbar"
assert self.c.biz.setdefault("otherbaz", "otherboz") == "otherboz"
assert self.c.biz.otherbaz == "otherboz"
def update(self):
self.c.update({"newkey": "newval"})
assert self.c["newkey"] == "newval"
assert self.c.foo == "bar"
self.c.biz.update(otherbaz="otherboz")
assert self.c.biz.otherbaz == "otherboz"