Commit e2abeb9c authored by Jim Fulton's avatar Jim Fulton Committed by GitHub

Added configuration-file syntax reference (#361)

* Added configuration-file syntax reference
parent 73dd4869
...@@ -338,6 +338,147 @@ use-dependency-links, default: true ...@@ -338,6 +338,147 @@ use-dependency-links, default: true
versions, default 'versions' versions, default 'versions'
The name of a section that contains :ref:`version pins <pinned-versions>`. The name of a section that contains :ref:`version pins <pinned-versions>`.
Configuration file syntax
=========================
Buildout configurations use an `INI file format
<https://en.wikipedia.org/wiki/INI_file>`_.
A configuration is a collection of named sections containing named
options.
Section names
-------------
A section begins with a section and and, optionally, a condition in
square braces (``[`` and ``]``).
A name can consist of any characters other than whitespace, square
braces, curly braced (``{`` or ``}``), pound signs (``#``), colons
(``:``) or semi-colons (``;``). The name may be surrounded by leading
and trailing whitespace, which is ignored.
An optional condition is separated from the name by a colon and is a
Python expression. It may not contain a pound sign or semi-colon. See
the section on :ref:`conditional sections <conditional-sections>` for
an example and more details.
A comment, preceded by a pound sign or semicolon may follow the
section name, as in:
.. code-block:: ini
[buildout] # This is the buildout section
.. -> header
Options
-------
Options are specified with an option name followed by an equal sign
and a value:
.. code-block:: ini
parts = py
.. -> option
>>> import six
>>> import zc.buildout.configparser
>>> def parse(s):
... return zc.buildout.configparser.parse(six.StringIO(s), 'test')
>>> from pprint import pprint
>>> pprint(parse(header + option))
{'buildout': {'parts': 'py'}}
Option names may have any characters other than whitespace, square
braces, curly braces equal signs or colons. There may be and usually
is whitespace between the name and the equal sign and the name and
equal sign must be on the same line.
Option values may contain any characters. A consequence of this is
that there can't be comments in option values.
Option values may be continued on multiple lines, and may contain blank lines:
.. code-block:: ini
parts = py
test
.. -> option
Whitespace in option values
___________________________
Trailing whitespace is stripped from each line in an option value.
Leading and trailing blank lines are stripped from option values.
Handling of leading whitespace and blank lines internal to values
depend on whether there is data on the first line (containing the
option name).
data on the first line
Leading whitespace is stripped and blank lines are omitted.
The resulting option value in the example above is:
.. code-block:: ini
py
test
.. -> val
>>> eq(parse(header + option)['buildout']['parts'] + '\n', val)
no data on the first line
Internal blank lines are retained and common leading white space is stripped.
For example, the value of the option:
.. code-block:: ini
code =
if x == 1:
y = 2 # a comment
return
.. -> option
is::
if x == 1:
y = 2 # a comment
return
.. -> val
>>> eq(parse(header + option)['buildout']['code'] + '\n', val)
Comments and blank lines
------------------------
Lines beginning with pound signs or semi-colons (``#`` or ``;``) are
comments::
# This is a comment
; This too
.. -> comment
>>> eq(parse(comment + header + comment + option + comment )
... ['buildout']['code'] + '\n', val)
As mentioned earlier, comments can also appear after section names.
Blank lines are ignored unless they're within option values that only
have data on continuation lines.
.. [#root-logger] Generally, the root logger format is used for all .. [#root-logger] Generally, the root logger format is used for all
messages unless it is overridden by a lower-level logger. messages unless it is overridden by a lower-level logger.
......
...@@ -131,6 +131,8 @@ extends-cache buildout option <extends-cache-buildout-option>`. ...@@ -131,6 +131,8 @@ extends-cache buildout option <extends-cache-buildout-option>`.
When a relative path is used in an extends option, it's interpreted When a relative path is used in an extends option, it's interpreted
relative to the path of the extending configuration. relative to the path of the extending configuration.
.. _conditional-sections:
Conditional configuration sections Conditional configuration sections
================================== ==================================
......
...@@ -3785,6 +3785,7 @@ def test_suite(): ...@@ -3785,6 +3785,7 @@ def test_suite():
manuel.testing.TestSuite( manuel.testing.TestSuite(
manuel.doctest.Manuel() + manuel.capture.Manuel(), manuel.doctest.Manuel() + manuel.capture.Manuel(),
os.path.join(docdir, 'getting-started.rst'), os.path.join(docdir, 'getting-started.rst'),
os.path.join(docdir, 'reference.rst'),
os.path.join(docdir, 'topics', 'bootstrapping.rst'), os.path.join(docdir, 'topics', 'bootstrapping.rst'),
os.path.join( os.path.join(
docdir, docdir,
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment