diff --git a/doc/source/generator.rst b/doc/source/cli/generator.rst
similarity index 99%
rename from doc/source/generator.rst
rename to doc/source/cli/generator.rst
index a42882b..ed5c3ed 100644
--- a/doc/source/generator.rst
+++ b/doc/source/cli/generator.rst
@@ -289,7 +289,7 @@ where the top-level keys are:
   the ``OptGroup`` they are assigned to which defaults to ``DEFAULT`` if unset.
 
   For information on the various attributes of each option, refer to
-  :doc:`opts`.
+  :ref:`option-definitions`.
 
 ``deprecated_options``
 
diff --git a/doc/source/cli/index.rst b/doc/source/cli/index.rst
new file mode 100644
index 0000000..b81f89f
--- /dev/null
+++ b/doc/source/cli/index.rst
@@ -0,0 +1,9 @@
+================================
+ oslo.config Command Line Tools
+================================
+
+.. toctree::
+   :maxdepth: 2
+
+   generator
+
diff --git a/doc/source/contributing.rst b/doc/source/contributor/index.rst
similarity index 53%
rename from doc/source/contributing.rst
rename to doc/source/contributor/index.rst
index 2ca75d1..ed5290b 100644
--- a/doc/source/contributing.rst
+++ b/doc/source/contributor/index.rst
@@ -2,4 +2,4 @@
  Contributing
 ==============
 
-.. include:: ../../CONTRIBUTING.rst
+.. include:: ../../../CONTRIBUTING.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index cddbd82..4fa2eb5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,5 +1,6 @@
-oslo.config
-===========
+=============
+ oslo.config
+=============
 
 An OpenStack library for parsing configuration options from the command
 line and configuration files.
@@ -10,24 +11,9 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   cfg
-   opts
-   types
-   configopts
-   cfgfilter
-   helpers
-   fixture
-   parser
-   exceptions
-   namespaces
-   styleguide
-   mutable
-   generator
-   builtins
-   sphinxext
-   sphinxconfiggen
-   faq
-   contributing
+   reference/index
+   cli/index
+   contributor/index
 
 Indices and tables
 ==================
diff --git a/doc/source/builtins.rst b/doc/source/reference/builtins.rst
similarity index 100%
rename from doc/source/builtins.rst
rename to doc/source/reference/builtins.rst
diff --git a/doc/source/cfg.rst b/doc/source/reference/cfg.rst
similarity index 100%
rename from doc/source/cfg.rst
rename to doc/source/reference/cfg.rst
diff --git a/doc/source/cfgfilter.rst b/doc/source/reference/cfgfilter.rst
similarity index 100%
rename from doc/source/cfgfilter.rst
rename to doc/source/reference/cfgfilter.rst
diff --git a/doc/source/configopts.rst b/doc/source/reference/configopts.rst
similarity index 100%
rename from doc/source/configopts.rst
rename to doc/source/reference/configopts.rst
diff --git a/doc/source/exceptions.rst b/doc/source/reference/exceptions.rst
similarity index 100%
rename from doc/source/exceptions.rst
rename to doc/source/reference/exceptions.rst
diff --git a/doc/source/faq.rst b/doc/source/reference/faq.rst
similarity index 100%
rename from doc/source/faq.rst
rename to doc/source/reference/faq.rst
diff --git a/doc/source/fixture.rst b/doc/source/reference/fixture.rst
similarity index 100%
rename from doc/source/fixture.rst
rename to doc/source/reference/fixture.rst
diff --git a/doc/source/helpers.rst b/doc/source/reference/helpers.rst
similarity index 100%
rename from doc/source/helpers.rst
rename to doc/source/reference/helpers.rst
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..23f2d3c
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,24 @@
+===================
+ Using oslo.config
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   cfg
+   opts
+   types
+   configopts
+   cfgfilter
+   helpers
+   fixture
+   parser
+   exceptions
+   namespaces
+   styleguide
+   mutable
+   builtins
+   sphinxext
+   sphinxconfiggen
+   faq
+
diff --git a/doc/source/mutable.rst b/doc/source/reference/mutable.rst
similarity index 100%
rename from doc/source/mutable.rst
rename to doc/source/reference/mutable.rst
diff --git a/doc/source/namespaces.rst b/doc/source/reference/namespaces.rst
similarity index 100%
rename from doc/source/namespaces.rst
rename to doc/source/reference/namespaces.rst
diff --git a/doc/source/opts.rst b/doc/source/reference/opts.rst
similarity index 95%
rename from doc/source/opts.rst
rename to doc/source/reference/opts.rst
index ccdf9a3..aaf5ead 100644
--- a/doc/source/opts.rst
+++ b/doc/source/reference/opts.rst
@@ -1,3 +1,5 @@
+.. _option-definitions:
+
 ------------------
 Option Definitions
 ------------------
diff --git a/doc/source/parser.rst b/doc/source/reference/parser.rst
similarity index 100%
rename from doc/source/parser.rst
rename to doc/source/reference/parser.rst
diff --git a/doc/source/sphinxconfiggen.rst b/doc/source/reference/sphinxconfiggen.rst
similarity index 100%
rename from doc/source/sphinxconfiggen.rst
rename to doc/source/reference/sphinxconfiggen.rst
diff --git a/doc/source/sphinxext.rst b/doc/source/reference/sphinxext.rst
similarity index 100%
rename from doc/source/sphinxext.rst
rename to doc/source/reference/sphinxext.rst
diff --git a/doc/source/styleguide.rst b/doc/source/reference/styleguide.rst
similarity index 100%
rename from doc/source/styleguide.rst
rename to doc/source/reference/styleguide.rst
diff --git a/doc/source/types.rst b/doc/source/reference/types.rst
similarity index 100%
rename from doc/source/types.rst
rename to doc/source/reference/types.rst