diff --git a/.gitignore b/.gitignore
index f290f27..56f1370 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,3 +55,4 @@ ChangeLog
 
 # generated docs
 doc/source/api
+doc/source/gnocchi.rst
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 149702f..d4f58b0 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -26,6 +26,7 @@ sys.path.insert(0, BASE_DIR)
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    'gnocchiclient.gendoc',
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx'
 ]
diff --git a/doc/source/shell.rst b/doc/source/shell.rst
index 0455ca2..ec1625b 100644
--- a/doc/source/shell.rst
+++ b/doc/source/shell.rst
@@ -7,6 +7,9 @@ The :program:`gnocchi` shell utility
 The :program:`gnocchi` shell utility interacts with Gnocchi from the command
 line. It supports the entirety of the Gnocchi API.
 
+Authentication method
++++++++++++++++++++++
+
 You'll need to provide the authentication method and your credentials to
 :program:`gnocchi`.
 
@@ -44,8 +47,8 @@ in your environment::
 Basic authentication
 ~~~~~~~~~~~~~~~~~~~~
 
-If you're using Gnocchi with basic authentication, export the following variables
-in your environment::
+If you're using Gnocchi with basic authentication, export the following
+variables in your environment::
 
   export OS_AUTH_TYPE=gnocchi-basic
   export GNOCCHI_USER=<youruserid>
@@ -82,28 +85,8 @@ environment variables::
     export GNOCCHI_USER_ID=99aae-4dc2-4fbc-b5b8-9688c470d9cc
     export GNOCCHI_PROJECT_ID=c8d27445-48af-457c-8e0d-1de7103eae1f
 
-Usage
-=====
 
-Once authentication is set up, all shell commands take the form::
+Commands descriptions
++++++++++++++++++++++
 
-    gnocchi <command> [arguments...]
-
-Run :program:`gnocchi help` to get a full list of all possible commands,
-and run :program:`gnocchi help <command>` to get detailed help for that
-command.
-
-Examples
---------
-
-Create a resource::
-
-    gnocchi resource create --attribute id:5a301761-f78b-46e2-8900-8b4f6fe6675a --attribute project_id:eba5c38f-c3dd-4d9c-9235-32d430471f94 -n temperature:high instance
-
-List resources::
-
-    gnocchi resource list --type instance
-
-Search of resources::
-
-    gnocchi resource search "project_id='5a301761-f78b-46e2-8900-8b4f6fe6675a' and type=instance"
+.. include:: gnocchi.rst
diff --git a/gnocchiclient/gendoc.py b/gnocchiclient/gendoc.py
new file mode 100644
index 0000000..17db0ff
--- /dev/null
+++ b/gnocchiclient/gendoc.py
@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+#
+# Licensed under the Apache License, Version 2.0 (the "License"); you may
+# not use this file except in compliance with the License. You may obtain
+# a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+# License for the specific language governing permissions and limitations
+# under the License.
+
+from __future__ import absolute_import
+
+from os_doc_tools import commands
+
+# HACK(jd) Not sure why but Sphinx setup this multiple times, so we just avoid
+# doing several times the requests by using this global variable :(
+_RUN = False
+
+
+def setup(app):
+    global _RUN
+    if _RUN:
+        return
+    commands.document_single_project("gnocchi", "doc/source", False)
+    with open("doc/source/gnocchi.rst", "r") as f:
+        data = f.read().splitlines(True)
+        for index, line in enumerate(data):
+            if "This chapter documents" in line:
+                break
+    with open("doc/source/gnocchi.rst", "w") as f:
+        f.writelines(data[index+1:])
+    _RUN = True
diff --git a/setup.cfg b/setup.cfg
index 7052832..4064301 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -84,8 +84,10 @@ test =
   testtools>=1.4.0
 
 doc =
+  doc8
   sphinx!=1.2.0,!=1.3b1,>=1.1.2
   oslosphinx>=2.5.0 # Apache-2.0
+  openstack-doc-tools>=1.0.1
 
 
 [build_sphinx]
diff --git a/tox.ini b/tox.ini
index 715bcc1..f489637 100644
--- a/tox.ini
+++ b/tox.ini
@@ -31,12 +31,15 @@ deps = .[test,doc]
 commands =
    rm -rf doc/source/ref
    python setup.py build_sphinx
+   doc8 --ignore-path doc/source/gnocchi.rst doc/source
 
 [testenv:docs-gnocchi.xyz]
 deps = .[test,doc]
        sphinx_rtd_theme
 setenv = SPHINX_HTML_THEME=sphinx_rtd_theme
-commands = python setup.py build_sphinx
+commands =
+   python setup.py build_sphinx
+   doc8 --ignore-path doc/source/gnocchi.rst doc/source
 
 [testenv:debug]
 commands = pifpaf --debug run gnocchi -- oslo_debug_helper {posargs}