configglue team mailing list archive

[Ricardo Kirkner <ricardo.kirkner@xxxxxxxxxxxxx>]

Ricardo Kirkner has proposed merging lp:~ricardokirkner/configglue/update-docs into lp:configglue.

Requested reviews:
  Configglue developers (configglue)

For more details, see:
https://code.launchpad.net/~ricardokirkner/configglue/update-docs/+merge/67436

updated documentation

added missing documentation for the 0,11 release
-- 
https://code.launchpad.net/~ricardokirkner/configglue/update-docs/+merge/67436
Your team Configglue developers is requested to review the proposed merge of lp:~ricardokirkner/configglue/update-docs into lp:configglue.

=== modified file 'configglue/__init__.py'
--- configglue/__init__.py	2011-06-23 23:58:43 +0000
+++ configglue/__init__.py	2011-07-09 19:57:26 +0000
@@ -15,4 +15,4 @@
 #
 ###############################################################################
 
-__version__ = '0.11'
+__version__ = '0.11.1'

=== modified file 'doc/conf.py'
--- doc/conf.py	2011-04-02 21:56:46 +0000
+++ doc/conf.py	2011-07-09 19:57:26 +0000
@@ -2,18 +2,14 @@
 #
 # configglue documentation build configuration file
 #
-#
-# This file is execfile()d with the current directory set to its containing dir.
-#
-# Note that not all possible configuration values are present in this
-# autogenerated file.
-#
-# All configuration values have a default; values that are commented out
-# serve to show the default.
 
 import sys
 import os
 
+# import configglue, to introspect the version string
+sys.path.insert(0, os.path.abspath('..'))
+import configglue
+
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -32,44 +28,28 @@
 source_suffix = '.rst'
 
 # The encoding of source files.
-#source_encoding = 'utf-8'
+source_encoding = 'utf-8'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General information about the project.
 project = u'configglue'
-copyright = u'John R. Lenton, Ricardo Kirkner'
+copyright = u'Ricardo Kirkner, John R. Lenton'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.10'
+version = configglue.__version__
 # The full version, including alpha/beta/rc tags.
-release = '0.10'
-
-# The language for content autogenerated by Sphinx. Refer to documentation
-# for a list of supported languages.
-#language = None
-
-# There are two options for replacing |today|: either, you set today to some
-# non-false value, then it is used:
-#today = ''
-# Else, today_fmt is used as the format for a strftime call.
-#today_fmt = '%B %d, %Y'
-
-# List of documents that shouldn't be included in the build.
-#unused_docs = []
+release = configglue.__version__
 
 # List of directories, relative to source directory, that shouldn't be searched
 # for source files.
 exclude_trees = ['_build']
 
-# The reST default role (used for this markup: `text`) to use for all documents.
-#default_role = None
-
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -77,10 +57,6 @@
 # unit titles (such as .. function::).
 add_module_names = False
 
-# If true, sectionauthor and moduleauthor directives will be shown in the
-# output. They are ignored by default.
-#show_authors = False
-
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
@@ -94,102 +70,25 @@
 # Sphinx are currently 'default' and 'sphinxdoc'.
 html_theme = 'default'
 
-# Theme options are theme-specific and customize the look and feel of a theme
-# further.  For a list of options available for each theme, see the
-# documentation.
-#html_theme_options = {}
-
-# Add any paths that contain custom themes here, relative to this directory.
-#html_theme_path = []
-
-# The name for this set of Sphinx documents.  If None, it defaults to
-# "<project> v<release> 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 (relative to this directory) to place at the top
-# of the sidebar.
-#html_logo = None
-
-# The name of an image file (within the static path) to use as favicon of the
-# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
-# pixels large.
-#html_favicon = None
-
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
-# using the given strftime format.
-#html_last_updated_fmt = '%b %d, %Y'
-
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 html_use_smartypants = True
 
-# Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
-
-# Additional templates that should be rendered to pages, maps page names to
-# template names.
-#html_additional_pages = {}
-
-# If false, no module index is generated.
-#html_use_modindex = True
-
-# If false, no index is generated.
-#html_use_index = True
-
-# If true, the index is split into individual pages for each letter.
-#html_split_index = False
-
-# If true, links to the reST sources are added to the pages.
-#html_show_sourcelink = True
-
-# If true, an OpenSearch description file will be output, and all pages will
-# contain a <link> tag referring to it.  The value of this option must be the
-# base URL from which the finished HTML is served.
-#html_use_opensearch = ''
-
-# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
-#html_file_suffix = ''
-
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'configgluedoc'
 
 
 # -- Options for LaTeX output --------------------------------------------------
 
-# The paper size ('letter' or 'a4').
-#latex_paper_size = 'letter'
-
-# The font size ('10pt', '11pt' or '12pt').
-#latex_font_size = '10pt'
-
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'configglue.tex', u'configglue Documentation',
-   u'John R. Lenton, Ricardo Kirkner', 'manual'),
+   u'Ricardo Kirkner, John R. Lenton', 'manual'),
 ]
 
-# The name of an image file (relative to this directory) to place at the top of
-# the title page.
-#latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-#latex_use_parts = False
-
-# Additional stuff for the LaTeX preamble.
-#latex_preamble = ''
-
-# Documents to append as an appendix to all manuals.
-#latex_appendices = []
-
-# If false, no module index is generated.
-#latex_use_modindex = True

=== modified file 'doc/howto/custom-schema-options.rst'
--- doc/howto/custom-schema-options.rst	2011-06-18 14:50:01 +0000
+++ doc/howto/custom-schema-options.rst	2011-07-09 19:57:26 +0000
@@ -82,6 +82,6 @@
 
 .. note::
     Note that the dictionary values are strings because we didn't specify an
-    item type for the ``UpperCaseDictOption``, and so it defaulted to
-    :class:`~configglue.pyschema.schema.StringOption`.
+    item type for the ``UpperCaseDictOption``, and so it defaulted
+    to :class:`~configglue.pyschema.schema.StringOption`.
 

=== modified file 'doc/index.rst'
--- doc/index.rst	2011-06-18 14:50:01 +0000
+++ doc/index.rst	2011-07-09 19:57:26 +0000
@@ -43,15 +43,27 @@
 The configuration file
 ======================
 
-    * **Configuration files:**
+    * **Basic:**
       :doc:`Syntax overview <topics/config-file>`
 
+    * **Advanced:**
+      :doc:`Environment variables <topics/environment-variables>`
+
 The command-line
 ================
 
-    * **Command-line integration:**
+    * **Basic:**
       :doc:`Overview <topics/command-line>`
 
+    * **Advanced:**
+      :doc:`Environment variables <topics/environment-variables>`
+
+Applications
+============
+
+    * **Getting started:**
+      :doc:`Writing configglue-enabled applications <topics/base-app>`
+
 The configglue open-source project
 ==================================
 

=== modified file 'doc/intro/install.rst'
--- doc/intro/install.rst	2011-04-21 02:42:18 +0000
+++ doc/intro/install.rst	2011-07-09 19:57:26 +0000
@@ -35,7 +35,7 @@
 
     >>> import configglue
     >>> print configglue.__version__
-    0.10
+    |version|
 
 
 That's it!

=== added directory 'doc/ref/app'
=== added file 'doc/ref/app/base.rst'
--- doc/ref/app/base.rst	1970-01-01 00:00:00 +0000
+++ doc/ref/app/base.rst	2011-07-09 19:57:26 +0000
@@ -0,0 +1,67 @@
+================================
+Application base class reference
+================================
+
+.. module:: configglue.app.base
+    :synopsis: Base class for configglue-enabled application.
+
+.. currentmodule:: configglue.app
+
+This document contains details about the base class provided by configglue
+for writing configglue-enabled applications.
+
+``App``
+-------
+
+.. class:: App([schema=None, plugin_manager=None, name=None, create_dirs=True])
+
+This is the base class from which your application should inherit in order to
+easily integrate itself with configglue.
+
+More details about what kind of benefits this provides are depicted in the
+introduction to
+:doc:`writing configglue-enabled applications </topics/base-app>`.
+
+.. attribute:: App.schema
+
+    *Optional*.
+
+    This is the schema class for the application. This schema should describe
+    application-wide configuration.
+
+    The schema can also be specified as a class attribute of subclasses of
+    :class:`~configglue.app.App`.
+
+.. attribute:: App.plugin_manager
+
+    *Optional*.
+
+    This is the class used to manage plugins. Should be an subclass of
+    :class:`~configglue.app.plugin.PluginManager`.
+
+    The default :class:`~configglue.app.plugin.PluginManager` will be used if
+    none is specified.
+
+    The plugin manager can also be specified as a class attribute of subclasses of
+    :class:`~configglue.app.App`.
+
+.. attribute:: App.name
+
+    *Optional*.
+
+    The name of the application. This value will be used to determine where to
+    look for configuration files.
+
+    If none is provided, the application will take the name of the script used
+    to invoke it from the command line.
+
+.. attribute:: App.create_dirs
+
+    *Optional*.
+
+    If ``False``, directories where configuration files are looked for will
+    not get created if they don't exist.
+
+    The default is to create non-existant directories.
+
+

=== added file 'doc/ref/app/index.rst'
--- doc/ref/app/index.rst	1970-01-01 00:00:00 +0000
+++ doc/ref/app/index.rst	2011-07-09 19:57:26 +0000
@@ -0,0 +1,13 @@
+============
+Applications
+============
+
+Application API reference. For introductory material, see
+:doc:`/topics/base-app`.
+
+.. toctree::
+   :maxdepth: 1
+
+   base
+   plugin
+

=== added file 'doc/ref/app/plugin.rst'
--- doc/ref/app/plugin.rst	1970-01-01 00:00:00 +0000
+++ doc/ref/app/plugin.rst	2011-07-09 19:57:26 +0000
@@ -0,0 +1,76 @@
+================
+Plugin reference
+================
+
+.. module:: configglue.app.plugin
+    :synopsis: Base classes for plugins and plugin managers.
+
+.. currentmodule:: configglue.app
+
+This document contains details about the base classes provided by configglue
+for writing plugins and plugin managers.
+
+``Plugin``
+----------
+
+.. class:: Plugin()
+
+This is the base class from which your plugins should inherit in order to
+integrate with your configglue-enabled application.
+
+.. attribute:: Plugin.schema
+
+    This is the schema class describing any configuration specific to your
+    plugin.
+
+    By default a standard :class:`~configglue.pyschema.schema.Schema` is used.
+
+.. attribute:: Plugin.enabled
+
+    Whether the plugin is enabled.
+
+    By default new plugins are *disabled*.
+
+
+``PluginManager``
+-----------------
+
+.. class:: PluginManager()
+
+This is the base class from which any custom plugin managers should inherit.
+
+.. attribute:: PluginManager.available
+
+    The list of currently available plugin classes.
+
+.. attribute:: PluginManager.enabled
+
+    The list of currently enabled plugin classes.
+
+.. attribute:: PluginManager.schemas
+
+    The list of schemas for the currently enabled plugins.
+
+.. method:: PluginManager.enable(plugin)
+
+    Enable the plugin.
+
+    *plugin* is the plugin *class*.
+
+.. method:: PluginManager.disable(plugin)
+
+    Disable the plugin.
+
+    *plugin* is the plugin *class*.
+
+.. method:: PluginManager.register(plugin)
+
+    Register the plugin by adding it to the list of available plugins.
+
+    *plugin* is the plugin *class*.
+
+.. method:: PluginManager.load()
+
+    Load plugins.
+
+    Return the list of classes for the loaded plugins.

=== modified file 'doc/ref/index.rst'
--- doc/ref/index.rst	2011-04-02 21:55:48 +0000
+++ doc/ref/index.rst	2011-07-09 19:57:26 +0000
@@ -6,4 +6,5 @@
    :maxdepth: 1
 
    schemas/index
+   app/index
 

=== modified file 'doc/ref/schemas/options.rst'
--- doc/ref/schemas/options.rst	2011-06-18 14:50:01 +0000
+++ doc/ref/schemas/options.rst	2011-07-09 19:57:26 +0000
@@ -74,7 +74,7 @@
 .. attribute:: Option.help
 
 The help text describing this option. This text will be used as the
-``optparse.OptParser`` help text.
+``optparse.OptionParser`` help text.
 
 Default is ``''``.
 
@@ -97,6 +97,14 @@
 .. 
 ..  Default is ``'store'``.
 
+``short_name``
+--------------
+
+.. attribute:: Option.short_name
+
+The short form name of the option. This will be used to set the short form
+parameter of the ``optparse.OptionParser`` used for parsing the command line.
+
 .. _schema-option-types:
 
 Option types

=== added file 'doc/topics/base-app.rst'
--- doc/topics/base-app.rst	1970-01-01 00:00:00 +0000
+++ doc/topics/base-app.rst	2011-07-09 19:57:26 +0000
@@ -0,0 +1,68 @@
+=======================================
+Writing configglue-enabled applications
+=======================================
+
+By inheriting from :class:`~configglue.app.App`, your application will
+reap the benefits of being able to
+
+Read configuration files from standard locations
+================================================
+
+The configglue-enabled app will automatically follow the XDG_ standards for
+looking up configuration files. For example, if your application is named
+*myapp*, the following locations will be searched for configuration values::
+
+    /etc/xdg/myapp/myapp.cfg
+    /home/<user>/.config/myapp/myapp.cfg
+    ./local.cfg
+
+Support plugins for extending your application
+==============================================
+
+The class :class:`~configglue.app.Plugin` will allow you to write plugins for
+your application so that each plugin can have it's own configglue-based
+configuration.
+
+Each plugin registered with the application will have it's own schema and
+configuration files, which will be included during validation. If the plugin
+is named *myplugin*, the following additional locations will be searched for
+configuration values::
+
+    /etc/xdg/myapp/myplugin.cfg
+    /home/<user>/.config/myapp/myplugin.cfg
+
+Plugins need to be registered with the application manually for the time
+being. For doing so, just call :meth:`~configglue.app.App.plugins.register`,
+like::
+
+    class FooSchema(Schema):
+        bar = IntOption()
+
+    class Foo(Plugin):
+        enabled = True
+        schema = FooSchema
+
+    myapp = App(name='myapp')
+    myapp.plugins.register(Foo)
+
+This example will register a `Foo` plugin which will be enabled by default.
+
+Plugins can be enabled/disabled on demand, by calling the respective method
+::
+
+    >>> myapp.plugins.enable(Foo)
+    >>> print myapp.plugins.enabled
+    [<class 'Foo'>]
+
+    >>> myapp.plugins.disable(Foo)
+    >>> print myapp.plugins.enabled
+    []
+
+The list of available plugins can be retrieved like
+::
+
+    >>> print myapp.plugins.available
+    [<class 'Foo'>]
+
+
+.. _XDG: http://www.freedesktop.org/wiki/Specifications/basedir-spec

=== modified file 'doc/topics/command-line.rst'
--- doc/topics/command-line.rst	2011-04-29 19:42:13 +0000
+++ doc/topics/command-line.rst	2011-07-09 19:57:26 +0000
@@ -5,9 +5,9 @@
 One of the nicest things about configglue is its ability to easily integrate
 the command line for specifying or overriding configuration values.
 
-In the example given in the :doc:`quickstart guide </intro/quickstart>`, it can
-be seen how the command line is used to supply the value of a configuration
-option.
+In the example given in the :doc:`quickstart guide </intro/quickstart>`, it
+can be seen how the command line is used to supply the value of a
+configuration option.
 
 Top-level configuration options are matched using the simple
 ::
@@ -24,3 +24,30 @@
 syntax; therefore it's not possible to have a section or option name contain
 underscore characters, as they would clash with the command line argument name
 resolution method.
+
+Short-form names
+================
+
+If the :class:`~configglue.pyschema.Option` has a non-empty
+:attr:`~configglue.pyschema.Option.short_name` set, this will be used as the
+short-form name for the command line parameter. For example, given the
+schema ::
+
+    class MySchema(pyschema.Schema):
+        foo = IntOption(short_name='f')
+
+the following forms of specifying a value for this option are equivalent::
+
+    --foo=1
+
+and
+::
+
+    -f 1
+
+Environment variables
+=====================
+
+Environment variables can be used for overriding configuration options. For
+more information, see the documentation about
+:ref:`environment-variables-command-line`.

=== modified file 'doc/topics/config-file.rst'
--- doc/topics/config-file.rst	2011-06-18 14:50:01 +0000
+++ doc/topics/config-file.rst	2011-07-09 19:57:26 +0000
@@ -112,3 +112,12 @@
 
     {'foo': 1, 'bar': True}
 
+
+Environment variables
+=====================
+
+You can also specify the value in the configuration file as an expression
+involving environment variables.
+
+For more details, refer to the documentation about
+:ref:`environment-variables-config-file`.

=== added file 'doc/topics/environment-variables.rst'
--- doc/topics/environment-variables.rst	1970-01-01 00:00:00 +0000
+++ doc/topics/environment-variables.rst	2011-07-09 19:57:26 +0000
@@ -0,0 +1,95 @@
+=====================
+Environment variables
+=====================
+
+Environment variables are now supported in two flavours
+
+.. _environment-variables-command-line:
+
+Environment variables during command-line integration
+=====================================================
+
+If an environment variable of the form
+
+CONFIGGLUE_FOO_BAR is defined, it will be used to override the configuration
+value for option foo in section bar, according to the following precedence
+rules:
+
+1. Explicitly defined via command-line (i.e, --section_option=value)
+2. Implicitly defined via environment variable (i.e, CONFIGGLUE_SECTION_OPTION)
+3. Explicitly defined via configuration files
+4. Implicitly defined via schema defaults
+
+To illustrate, a few examples. Given the example from the :doc:`quickstart
+guide </intro/quickstart>`, the following examples illustrate the precedence
+rules just mentioned.
+
+Implicitly defined via schema defaults
+::
+
+    $ python app.py
+    foo option has default value: 0
+    bar option has default value: False
+
+Implicitly defined via environment variable (overriding schema defaults)
+::
+
+    $ CONFIGGLUE_FOO=3 python app.py
+    foo option has been configured with value: 3
+    bar option has default value: False
+
+Explicitly defined via command-line
+::
+
+    $ CONFIGGLUE_FOO=3 python app.py --foo=2
+    foo option has been configured with value: 2
+    bar option has default value: False
+
+Explicitly defined via configuration files
+::
+
+    $ echo "[__main__]\nfoo = 5" > config.ini
+    $ python app.py
+    foo option has been configured with value: 5
+    bar option has default value: False
+
+Implicitly defined via environment variable (overriding config file)
+::
+
+    $ CONFIGGLUE_FOO=33 python app.py
+    foo option has been configured with value: 33
+    bar option has default value: False
+
+
+.. _environment-variables-config-file:
+
+Environment variables as placeholders in configuration files
+============================================================
+
+In the configuration files, if an option has a value such as
+
+$FOO
+
+or
+
+${FOO}
+
+it will be interpolated using the FOO environment variable, or if that
+variable is not defined, it will fallback to the default value for that
+option.
+
+Using the same example as shown in the :doc:`quickstart guide
+</intro/quickstart>`, this use case can be illustrated as follows.
+
+Specifying a value in the configuration file using an environment variable
+::
+
+    $ echo "[__main__]\nfoo = \$BAZ" > config.ini
+    $ BAZ=33 python app.py
+    foo option has been configured with value: 33
+
+If the environment variable is not defined, fallback to the default value
+::
+
+    $ python app.py
+    foo option has default value: 0

=== modified file 'doc/topics/index.rst'
--- doc/topics/index.rst	2011-04-21 02:42:18 +0000
+++ doc/topics/index.rst	2011-07-09 19:57:26 +0000
@@ -10,4 +10,6 @@
    schemas
    config-file
    command-line
+   environment-variables
+   base-app
 

=== modified file 'doc/topics/schemas.rst'
--- doc/topics/schemas.rst	2011-06-18 14:50:01 +0000
+++ doc/topics/schemas.rst	2011-07-09 19:57:26 +0000
@@ -2,8 +2,6 @@
 Schemas
 =======
 
-.. module:: configglue.pyschema.schema
-
 A schema is a static declaration of all your configuration settings. It
 contains metadata about each setting so that the configuration can later
 be validated.