Autobuild of dashboard overview plus various fixes

This adds a call in sphinx to automatically generate the dashboard
description pages.  It's a little bit of a hack, but works with "tox
-e docs" and the readthedocs build.  This means we don't have to have
an external job running a separate build of the dashboard overview
page.

A couple of other things to integrate this and make the docs more
usable; we use the readme as the main page, fix up the links, use
sections in the template and add a clickable link to the dashboard in
each overview page.

I'ved tested this with readthedocs which you can see at [1]

[1] http://gerrit-dash-creator-dashboards.readthedocs.org/en/latest/

Change-Id: I027a21a40a0e35817b8a29996a48393743b282b0

.gitignore

@@ -24,3 +24,4 @@ ChangeLog
 .bak
 
 doc/build/
+doc/source/dashboards

README.rst

@@ -44,8 +44,8 @@ the dashboard file you want the URL for::
 
 Then put the URL in your browser and off you go.
 
-A daily updated index of all available dashboards is available
+The latest dashboards are available at
-at `<https://readthedocs.org/gerrit-dash-creator>`__
+`<http://gerrit-dash-creator.readthedocs.org/en/latest/dashboards/index.html>`__
 
 
 Contributions Welcomed

doc/source/conf.py

@@ -12,6 +12,7 @@
 # limitations under the License.
 
 import os
+import subprocess
 import sys
 
 sys.path.insert(0, os.path.abspath('../..'))
@@ -68,3 +69,15 @@ latex_documents = [
      u'%s Documentation' % project,
      u'OpenStack Foundation', 'manual'),
 ]
+
+# this is a bit of a hack that generates the RST for each dashboard
+# dynamically and works from tox -e docs & on readthedocs.  It has to
+# put it in doc/source to get picked up as part of the build.
+def setup(app):
+    if os.getcwd().endswith("doc/source"):
+        prefix = "cd ../../;"
+    else:
+        prefix = ""
+
+    subprocess.call("%s ./tools/generate_dashboards.sh" % (prefix),
+                    shell=True)

doc/source/index.rst

@@ -1,20 +1,12 @@
-Welcome to gerrit-dash-creator's documentation!
+.. include:: ../../README.rst
-===============================================
 
-Contents:
+Further reading
+===============
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   readme
    installation
    usage
    contributing
-
+   dashboards/index
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
-

doc/source/readme.rst

@@ -1 +0,0 @@
-.. include:: ../../README.rst

templates/single.rst

@@ -2,17 +2,25 @@
 ==============================================================================
 
 {% if description %}
-Description::
+Description
-
+-----------
-    {{ description }}
+{{ description }}
 {%- endif %}
 
-URL::
+URL
+---
 
-    {{ url }}
+::
+
+   {{ url }}
+
+`View this dashboard <{{ url }}>`__
 
 {% if configuration %}
-Configuration::
+Configuration
+-------------
+
+::
 
 {% for line in configuration.splitlines() %}
     {{ line }}

tools/generate_dashboards.sh

@@ -1,4 +1,4 @@
-#!/bin/sh
+#!/bin/bash
 
 # 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
@@ -12,25 +12,20 @@
 # License for the specific language governing permissions and limitations
 # under the License.
 
-output_directory=doc/dashboards/
+set -x
 
-if [[ -e $output_directory ]]; then
+OUTPUT_DIRECTORY=${OUTPUT_DIRECTORY:-doc/source/dashboards/}
-    rm -f $output_directory/*
+
+if [[ -e $OUTPUT_DIRECTORY ]]; then
+    rm -f $OUTPUT_DIRECTORY/*
 else
-    mkdir -p $output_directory
+    mkdir -p $OUTPUT_DIRECTORY
 fi
 
-cp doc/source/conf.py $output_directory
-
-echo "
-html_theme_options = {
-    'nosidebar': True
-}" >> $output_directory/conf.py
-
 for dashboard in $(find dashboards -name '*.dash' | sort); do
     output=$(basename $dashboard .dash)
     python gerrit_dash_creator/cmd/creator.py --template-directory templates \
-    --template single.rst $dashboard > $output_directory/dashboard_$output.rst
+    --template single.rst $dashboard > $OUTPUT_DIRECTORY/dashboard_$output.rst
 done
 
 echo "===========================
@@ -38,9 +33,10 @@ OpenStack Gerrit Dashboards
 ===========================
 
 .. toctree::
-" >> $output_directory/index.rst
+   :maxdepth: 1
+" >> $OUTPUT_DIRECTORY/index.rst
 
-for dashboard in $(find $output_directory -name 'dashboard_*.rst' | sort); do
+for dashboard in $(find $OUTPUT_DIRECTORY -name 'dashboard_*.rst' | sort); do
     dashboard=$(basename $dashboard .rst)
-    echo "  " $dashboard >> $output_directory/index.rst
+    echo "  " $dashboard >> $OUTPUT_DIRECTORY/index.rst
 done

tox.ini

@@ -26,7 +26,8 @@ commands = python setup.py testr --coverage --testr-args='{posargs}'
 
 [testenv:docs]
 commands =
-  doc8 -e .rst doc CONTRIBUTING.rst HACKING.rst README.rst
+# not happy with generated dashboard pages
+#  doc8 -e .rst doc CONTRIBUTING.rst HACKING.rst README.rst
   python setup.py build_sphinx
 
 [flake8]