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
This commit is contained in:
Ian Wienand 2016-03-22 12:53:20 +11:00
parent e917bdbba6
commit 16fef44f00
8 changed files with 49 additions and 39 deletions

1
.gitignore vendored
View File

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

View File

@ -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
at `<https://readthedocs.org/gerrit-dash-creator>`__
The latest dashboards are available at
`<http://gerrit-dash-creator.readthedocs.org/en/latest/dashboards/index.html>`__
Contributions Welcomed

View File

@ -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)

View File

@ -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
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
dashboards/index

View File

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

View File

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

View File

@ -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
rm -f $output_directory/*
OUTPUT_DIRECTORY=${OUTPUT_DIRECTORY:-doc/source/dashboards/}
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

View File

@ -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]