diff --git a/.gitignore b/.gitignore
index 3aef07f..c1b4d16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -47,7 +47,7 @@ doc/build
 # pbr generates these
 AUTHORS
 ChangeLog
-/doc/source/api/
+doc/source/reference/api
 
 # Editors
 *~
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/history.rst b/doc/source/history.rst
deleted file mode 100644
index 69ed4fe..0000000
--- a/doc/source/history.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../ChangeLog
diff --git a/doc/source/index.rst b/doc/source/index.rst
index a5e66c3..245f2cd 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -10,26 +10,10 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   installation
-   usage
-   opts
-   contributing
-
-API
-===
-
-.. toctree::
-   :maxdepth: 2
-
-   api/autoindex
-
-Release Notes
-=============
-
-.. toctree::
-   :maxdepth: 1
-
-   history
+   install/index
+   contributor/index
+   user/index
+   reference/index
 
 Indices and tables
 ==================
diff --git a/doc/source/installation.rst b/doc/source/install/index.rst
similarity index 55%
rename from doc/source/installation.rst
rename to doc/source/install/index.rst
index 042f75c..7179ffa 100644
--- a/doc/source/installation.rst
+++ b/doc/source/install/index.rst
@@ -1,6 +1,6 @@
-==============
- Installation
-==============
+============
+Installation
+============
 
 At the command line::
 
diff --git a/doc/source/reference/index.rst b/doc/source/reference/index.rst
new file mode 100644
index 0000000..9eb4867
--- /dev/null
+++ b/doc/source/reference/index.rst
@@ -0,0 +1,18 @@
+.. _using:
+
+=========
+Reference
+=========
+
+.. toctree::
+   :maxdepth: 2
+
+   opts
+
+API
+===
+
+.. toctree::
+   :maxdepth: 1
+
+   api/autoindex
diff --git a/doc/source/opts.rst b/doc/source/reference/opts.rst
similarity index 66%
rename from doc/source/opts.rst
rename to doc/source/reference/opts.rst
index 205e30d..315db6e 100644
--- a/doc/source/opts.rst
+++ b/doc/source/reference/opts.rst
@@ -1,6 +1,8 @@
-=======================
- Configuration Options
-=======================
+.. _option-definitions:
+
+=====================
+Configuration Options
+=====================
 
 oslo.reports uses oslo.config to define and manage configuration options
 to allow the deployer to control where the GMR reports should be generated.
diff --git a/doc/source/user/history.rst b/doc/source/user/history.rst
new file mode 100644
index 0000000..f69be70
--- /dev/null
+++ b/doc/source/user/history.rst
@@ -0,0 +1 @@
+.. include:: ../../../ChangeLog
diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
new file mode 100644
index 0000000..6f078b9
--- /dev/null
+++ b/doc/source/user/index.rst
@@ -0,0 +1,9 @@
+===================
+ Using oslo.reports
+===================
+
+.. toctree::
+   :maxdepth: 2
+
+   usage
+   history
diff --git a/doc/source/report.txt b/doc/source/user/report.txt
similarity index 99%
rename from doc/source/report.txt
rename to doc/source/user/report.txt
index 8f3c446..de665ef 100644
--- a/doc/source/report.txt
+++ b/doc/source/user/report.txt
@@ -752,4 +752,4 @@ workarounds:
   destroy_after_evacuate = True
   disable_libvirt_livesnapshot = True
   disable_rootwrap = False
-  handle_virt_lifecycle_events = True
\ No newline at end of file
+  handle_virt_lifecycle_events = True
diff --git a/doc/source/usage.rst b/doc/source/user/usage.rst
similarity index 100%
rename from doc/source/usage.rst
rename to doc/source/user/usage.rst
diff --git a/setup.cfg b/setup.cfg
index c603e61..66c9547 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -24,6 +24,7 @@ packages =
 
 [pbr]
 autodoc_index_modules = true
+api_doc_dir = reference/api
 autodoc_exclude_modules =
     oslo_reports._i18n
     oslo_reports._utils