diff --git a/roles/validate-tempest/templates/configure-tempest.sh.j2 b/roles/validate-tempest/templates/configure-tempest.sh.j2
index 87f124b7e..eef415342 100644
--- a/roles/validate-tempest/templates/configure-tempest.sh.j2
+++ b/roles/validate-tempest/templates/configure-tempest.sh.j2
@@ -1,13 +1,20 @@
-#
-# configure-tempest
-#
+### --start_docs
+
+## Configure tempest
+## -----------------
+
 {% if tempest_overcloud %}
+## ::
 source {{ working_dir }}/overcloudrc
 
-# Clean up from any previous tempest run.
+## * Clean up from any previous tempest run
+## ::
+
 rm -rf {{ working_dir }}/tempest
 
-# clean up network if it exists from previous run
+## * Clean up network if it exists from previous run
+## ::
+
 for i in $(neutron router-list -c id -f value); do neutron router-gateway-clear $i; done
 for r in $(neutron router-list -c id -f value); do
     for p in $(neutron router-port-list $r -c id -f value); do
@@ -38,7 +45,9 @@ source {{ working_dir }}/stackrc
 public_net_id=$(neutron net-show {{ undercloud_public_net_name }} -f value -c id)
 {% endif %}
 
-# Generate a tempest configuration.
+## * Generate a tempest configuration
+## ::
+
 sudo yum install -y libffi-devel openssl-devel python-virtualenv gcc
 
 {% if tempest_source == "rdo" %}
@@ -68,9 +77,12 @@ cp /usr/share/openstack-tempest-*/etc/default-overrides.conf ./etc/
 {% endif %}
 
 {% if tempest_undercloud %}
-# config_tempest assumes that Cinder is installed and accessible. Cinder is
-# not installed on the undercloud. Remove unneeded lines to prevent the tool
-# from bawking upon execution
+
+## .. note:: config_tempest assumes that Cinder is installed and accessible. Cinder is
+##           not installed on the undercloud. Remove unneeded lines to prevent the tool
+##           from bawking upon execution
+## ::
+
 sed --in-place "/'volume'\: 'cinder',/d" tools/config_tempest.py
 sed --in-place "/'volume'\: \['v1', 'v2'\]/d" tools/config_tempest.py
 {% endif %}
@@ -91,3 +103,6 @@ sed --in-place "/'volume'\: \['v1', 'v2'\]/d" tools/config_tempest.py
   volume.build_timeout 500 \
   scenario.ssh_user cirros \
   orchestration.stack_owner_role heat_stack_owner
+
+### --stop_docs
+
diff --git a/roles/validate-tempest/templates/run-tempest.sh.j2 b/roles/validate-tempest/templates/run-tempest.sh.j2
index 6330aeb4d..0417e544e 100644
--- a/roles/validate-tempest/templates/run-tempest.sh.j2
+++ b/roles/validate-tempest/templates/run-tempest.sh.j2
@@ -1,4 +1,9 @@
-# Run tempest.
+### --start_docs
+
+## Run tempest
+## -----------
+
+## ::
 
 {% if tempest_format == "venv" %}./tools/with_venv.sh {% endif %}
 ./tools/run-tests.sh {{ test_regex }} {% if skip_file_src != '' %}--skip-file {{ working_dir }}/{{ skip_file }}{% endif %}
@@ -7,3 +12,6 @@
 {% if tempest_tests_file is defined %} --load-list={{ tempest_tests_file }} {% endif %}
 {% if tempest_until_failure|bool %} --until-failure {% endif %}
 {% if tempest_failing|bool %} --failing {% endif %}
+
+### --stop_docs
+
diff --git a/roles/validate-tempest/templates/tempest-setup.j2 b/roles/validate-tempest/templates/tempest-setup.j2
index 734ba7d44..321f468b0 100644
--- a/roles/validate-tempest/templates/tempest-setup.j2
+++ b/roles/validate-tempest/templates/tempest-setup.j2
@@ -1,10 +1,16 @@
 #!/bin/bash
-# Validate the overcloud deployment
 
 set -eux
 
 {% if configure_tempest|bool %}
+### --start_docs
+
+## Validate the overcloud deployment with tempest
+## ==============================================
+
 {% include 'configure-tempest.sh.j2' %}
 
 {% include 'run-tempest.sh.j2' %}
+
+### --stop_docs
 {% endif %}