diff --git a/CHANGES b/CHANGES index 89b07aedb..b61cfd3a0 100644 --- a/CHANGES +++ b/CHANGES @@ -19,6 +19,15 @@ New features added * The directories in the `html_static_path` can now contain subdirectories. +* The new config value `html_short_title` can be used to set a shorter + title for the documentation which is then used in the navigation bar. + +* The new config value `html_show_sphinx` can be used to control whether + a link to Sphinx is added to the HTML footer. + +* Defaults for configuration values can now be callables, which allows + dynamic defaults. + Bugs fixed ---------- @@ -40,7 +49,7 @@ Bugs fixed * Fix behavior of references to functions/methods with an explicit title. -* Support citation nodes in LaTeX writer. +* Support citation nodes in LaTeX writer.M v7 Release 0.3 (May 6, 2008) diff --git a/doc/config.rst b/doc/config.rst index ed1b7b149..838a013e5 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -182,6 +182,14 @@ that use Sphinx' HTMLWriter class. v{} documentation'`, where the placeholders are replaced by the config values of the same name. +.. confval:: html_short_title + + A shorter "title" for the HTML docs. This is used in for links in the header + and in the HTML Help docs. If not given, it defaults to the value of + :confval:`html_title`. + + .. versionadded:: 0.4 + .. confval:: html_style The style sheet to use for HTML pages. A file of that name must exist either @@ -293,6 +301,13 @@ that use Sphinx' HTMLWriter class. to translate document trees to HTML. Default is ``None`` (use the builtin translator). +.. confval:: html_show_sphinx + + If true, "Created using Sphinx" is shown in the HTML footer. Default is + ``True``. + + .. versionadded:: 0.4 + .. confval:: htmlhelp_basename Output file base name for HTML help builder. Default is ``'pydoc'``. diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index a0eeeeb75..616708ad8 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -24,6 +24,11 @@ the following public API: in the setting only takes effect when a document is parsed -- this means that the whole environment must be rebuilt. + .. versionchanged:: 0.4 + If the *default* value is a callable, it will be called with the config + object as its argument in order to get the default value. This can be + used to implement config values whose default depends on other values. + .. method:: Sphinx.add_event(name) Register an event called *name*. @@ -43,7 +48,7 @@ the following public API: documentation. .. XXX once we target docutils 0.5, update this - + .. method:: Sphinx.add_role(name, role) Register a Docutils role. *name* must be the role name that occurs in the diff --git a/sphinx/application.py b/sphinx/application.py index cfb9677d3..d136f0be5 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -79,16 +79,12 @@ class Sphinx(object): setattr(self.config, key, val) # load all extension modules - for extension in getattr(self.config, 'extensions', ()): + for extension in self.config.extensions: self.setup_extension(extension) # the config file itself can be an extension - if hasattr(self.config, 'setup'): + if self.config.setup: self.config.setup(self) - # this must happen after loading extension modules, since they - # can add custom config values - self.config.init_defaults() - if buildername is None: print >>status, 'No builder selected, using default: html' buildername = 'html' @@ -179,9 +175,10 @@ class Sphinx(object): self.builderclasses[builder.name] = builder def add_config_value(self, name, default, rebuild_env): - if name in self.config.values: + if name in self.config.valuenames: raise ExtensionError('Config value %r already present' % name) - self.config.values[name] = (default, rebuild_env) + self.config.valuenames.add(name) + self.config.__class__.config_values[name] = (default, rebuild_env) def add_event(self, name): if name in self._events: diff --git a/sphinx/builder.py b/sphinx/builder.py index b7ab1bf4d..f9e391735 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -320,9 +320,6 @@ class StandaloneHTMLBuilder(Builder): else: self.last_updated = None - docstitle = self.config.html_title or \ - '%s v%s documentation' % (self.config.project, - self.config.release) logo = self.config.html_logo and \ path.basename(self.config.html_logo) or '' @@ -339,7 +336,9 @@ class StandaloneHTMLBuilder(Builder): use_modindex = self.config.html_use_modindex, use_index = self.config.html_use_index, use_opensearch = self.config.html_use_opensearch, - docstitle = docstitle, + docstitle = self.config.html_title, + shorttitle = self.config.html_short_title, + show_sphinx = self.config.html_show_sphinx, builder = self.name, parents = [], titles = {}, @@ -913,17 +912,15 @@ class ChangesBuilder(Builder): otherchanges.setdefault((docname, title), []).append( (entry, docname, lineno)) - docstitle = self.config.html_title or \ - '%s v%s documentation' % (self.config.project, - self.config.release) - ctx = { 'project': self.config.project, 'version': version, - 'docstitle': docstitle, + 'docstitle': self.config.html_title, + 'shorttitle': self.config.html_short_title, 'libchanges': sorted(libchanges.iteritems()), 'apichanges': sorted(apichanges), 'otherchanges': sorted(otherchanges.iteritems()), + 'show_sphinx': self.config.html_show_sphinx, } f = open(path.join(self.outdir, 'index.html'), 'w') try: diff --git a/sphinx/config.py b/sphinx/config.py index 76ff2a820..dd6d12651 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -47,7 +47,10 @@ class Config(object): template_bridge = (None, False), # HTML options - html_title = (None, False), + html_title = (lambda self: '%s v%s documentation' % + (self.project, self.release), + False), + html_short_title = (lambda self: self.html_title, False), html_style = ('default.css', False), html_logo = (None, False), html_static_path = ([], False), @@ -61,6 +64,7 @@ class Config(object): html_copy_source = (True, False), html_use_opensearch = ('', False), html_file_suffix = (None, False), + html_show_sphinx = (True, False), # HTML help only options htmlhelp_basename = ('pydoc', False), @@ -77,7 +81,7 @@ class Config(object): ) def __init__(self, dirname, filename): - self.values = self.config_values.copy() + self.valuenames = set(self.config_values.keys()) config = {'__file__': path.join(dirname, filename)} olddir = os.getcwd() try: @@ -85,12 +89,20 @@ class Config(object): execfile(config['__file__'], config) finally: os.chdir(olddir) - self.__dict__.update(config) + for name in config: + if name in self.valuenames: + self.__dict__[name] = config[name] + self.setup = config.get('setup', None) - def init_defaults(self): - for val in self.values: - if val not in self.__dict__: - self.__dict__[val] = self.values[val][0] + def __getattr__(self, name): + if name.startswith('_'): + raise AttributeError(name) + if name not in self.valuenames: + raise AttributeError('No such config value: %s' % name) + default = self.config_values[name][0] + if callable(default): + return default(self) + return default def __getitem__(self, name): return getattr(self, name) @@ -102,4 +114,4 @@ class Config(object): delattr(self, name) def __contains__(self, name): - return hasattr(self, name) + return name in self.valuenames diff --git a/sphinx/htmlhelp.py b/sphinx/htmlhelp.py index 327b59a46..957821c1c 100644 --- a/sphinx/htmlhelp.py +++ b/sphinx/htmlhelp.py @@ -129,9 +129,8 @@ def build_hhx(builder, outdir, outname): builder.info('writing project file...') f = open(path.join(outdir, outname+'.hhp'), 'w') try: - title = builder.config.html_title or \ - '%s v%s documentation' % (builder.config.project, builder.config.release) - f.write(project_template % {'outname': outname, 'title': title, + f.write(project_template % {'outname': outname, + 'title': builder.config.html_title, 'version': builder.config.version, 'project': builder.config.project}) if not outdir.endswith(os.sep): @@ -150,7 +149,8 @@ def build_hhx(builder, outdir, outname): try: f.write(contents_header) # special books - f.write('
  • ' + object_sitemap % ('Main page', 'index.html')) + f.write('
  • ' + object_sitemap % (builder.config.html_short_title, + 'index.html')) if builder.config.html_use_modindex: f.write('
  • ' + object_sitemap % ('Global Module Index', 'modindex.html')) # the TOC diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 76d3f94cd..55869285a 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -105,6 +105,9 @@ html_style = 'default.css' # " v documentation". #html_title = None +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + # The name of an image file (within the static path) to place at the top of # the sidebar. #html_logo = None diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index dfda6f69b..d1fc566c8 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -25,7 +25,7 @@ title="Customize your viewing settings" accesskey="S">settings |
  • {%- endif %} {%- block rootrellink %} -
  • {{ docstitle }}{{ reldelim1 }}
  • +
  • {{ shorttitle }}{{ reldelim1 }}
  • {%- endblock %} {%- for parent in parents %}
  • {{ parent.title }}{{ reldelim1 }}
  • @@ -185,6 +185,9 @@ {%- if last_updated %} Last updated on {{ last_updated }}. {%- endif %} + {%- if show_sphinx %} + Created using Sphinx. + {%- endif %} {%- endblock %}