Merge "Add a Quick Start tutorial"

doc/source/configuration/index.rst

@@ -5,6 +5,7 @@
 .. toctree::
    :maxdepth: 2
 
+   quickstart
    format
    mutable
    options

doc/source/configuration/quickstart.rst

@@ -0,0 +1,78 @@
+==========================
+ oslo.config Quick Start!
+==========================
+
+Are you brand new to oslo.config? This brief tutorial will get you started
+understanding some of the fundamentals.
+
+Prerequisites
+-------------
+* A plain text editor or Python-enabled IDE
+* A Python interpreter
+* A command shell from which the interpreter can be invoked
+* The oslo_config library in your Python path.
+
+Test Script
+-----------
+Put this in a file called ``oslocfgtest.py``.
+
+.. code:: python
+
+  # The sys module lets you get at the command line arguments.
+  import sys
+
+  # Load up the cfg module, which contains all the classes and methods
+  # you'll need.
+  from oslo_config import cfg
+
+  # Define an option group
+  grp = cfg.OptGroup('mygroup')
+
+  # Define a couple of options
+  opts = [cfg.StrOpt('option1'),
+          cfg.IntOpt('option2', default=42)]
+
+  # Register your config group
+  cfg.CONF.register_group(grp)
+
+  # Register your options within the config group
+  cfg.CONF.register_opts(opts, group=grp)
+
+  # Process command line arguments.  The arguments tell CONF where to
+  # find your config file, which it loads and parses to populate itself.
+  cfg.CONF(sys.argv[1:])
+
+  # Now you can access the values from the config file as
+  # CONF.<group>.<opt>
+  print("The value of option1 is %s" % cfg.CONF.mygroup.option1)
+  print("The value of option2 is %d" % cfg.CONF.mygroup.option2)
+
+Conf File
+---------
+Put this in a file called ``oslocfgtest.conf`` in the same directory as
+``oslocfgtest.py``.
+
+.. code:: ini
+
+  [mygroup]
+  option1 = foo
+  # Comment out option2 to test the default value
+  # option2 = 123
+
+Run It!
+-------
+From your command shell, in the same directory as your script and conf, invoke:
+
+.. code:: shell
+
+  python oslocfgtest.py --config-file oslocfgtest.conf
+
+Revel in the output being exactly as expected.  If you've done everything
+right, you should see:
+
+.. code:: shell
+
+  The value of option1 is foo
+  The value of option2 is 42
+
+Now go play with some more advanced option settings!