diff --git a/README.md b/README.md deleted file mode 100644 index ecd5c08..0000000 --- a/README.md +++ /dev/null @@ -1,85 +0,0 @@ -StackViz -======== - -A visualization utility to help analyze the performance of DevStack setup and -Tempest executions. - -Installation ------------- -Installation of the frontend requires Node.js and Bower. On Ubuntu: -```bash -sudo apt-get install nodejs npm -sudo npm install -g bower -``` - -Then, install the Bower components by running, from the project directory, -```bash -bower install -``` - -Usage - Server --------------- -First, install the necessary dependencies with Pip: -```bash -sudo pip install -r requirements.txt -``` - -The Django development server may then be used to view the interface. Run: -```bash -python manage.py runserver -``` - -You can then browse to the printed URL in your browser of choice. - -Usage - Static Site -------------------- -The server can be "snapshotted" and exported to a static HTML site using the -`export_static.py` utility. StackViz can then be viewed using any web browser -with no requirement of any server-side processing. - -To generate, run: -```bash -python export_static.py dest_dir -``` - -... where `dest_dir` is the path to a target directory where files should be -written. When finished, the `index.html` file can be opened in a browser. - -Note that some browsers enforce content origin policies that may disallow -XHRs when viewed directly from the local filesystem. To work around this, you -can use something like the Python `SimpleHTTPServer`: -```bash -python -m SimpleHTTPServer -``` - -### GZipped Data -As the log data can become quite large, exported files can be compressed with -GZip to significantly reduce the size of the data files. To enable, run: -```bash -python export_static.py --gzip dest_dir -``` - -Data files will then be written in compressed form, and will be suffixed with -`*.json.gz`. Note that web servers must be properly configured to serve -pre-compressed files. Notably, Python's `SimpleHTTPServer` will not do this by -default. However, [Twisted](https://twistedmatrix.com/trac/) can be used as a -drop-in replacement as follows: -```bash -twistd -no web --path=. -``` - -Other web servers, such as Apache, should also serve these files correctly -without any extra configuration. - -(Specifically, the response must have headers `Content-Type: application/json` -and `Content-Encoding: gzip`.) - -Log Locations -------------- -Log locations are configured along with normal Django settings in -`stackviz/settings.py`. Several different types of logs are rendered by -StackViz: - - * Tempest (`testr` repositories): `./`, `/opt/stack/tempest/` - * DevStack: *TODO* - * Dstat: *TODO* diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..c31bcd3 --- /dev/null +++ b/README.rst @@ -0,0 +1,79 @@ +======== +StackViz +======== + +A visualization utility to help analyze the performance of DevStack setup and +Tempest executions. + +Installation +============ +Installation of the frontend requires Node.js and Bower. On Ubuntu:: + + sudo apt-get install nodejs npm + sudo npm install -g bower + +Then, install the Bower components by running, from the project directory:: + + bower install + +Usage - Server +============== +First, install the necessary dependencies with Pip:: + + sudo pip install -r requirements.txt + +The Django development server may then be used to view the interface. Run:: + + python manage.py runserver + +You can then browse to the printed URL in your browser of choice. + +Usage - Static Site +=================== +The server can be "snapshotted" and exported to a static HTML site using the +:code:`export_static.py` utility. StackViz can then be viewed using any web +browser with no requirement of any server-side processing. + +To generate, run:: + + python export_static.py dest_dir + +... where `dest_dir` is the path to a target directory where files should be +written. When finished, the :code:`index.html` file can be opened in a browser. + +Note that some browsers enforce content origin policies that may disallow +XHRs when viewed directly from the local filesystem. To work around this, you +can use something like the Python :code:`SimpleHTTPServer`:: + + python -m SimpleHTTPServer + +GZipped Data +------------ +As the log data can become quite large, exported files can be compressed with +GZip to significantly reduce the size of the data files. To enable, run:: + + python export_static.py --gzip dest_dir + +Data files will then be written in compressed form, and will be suffixed with +:code:`*.json.gz`. Note that web servers must be properly configured to serve +pre-compressed files. Notably, Python's :code:`SimpleHTTPServer` will not do +this by default. However, `Twisted `_ can be +used as a drop-in replacement as follows:: + + twistd -no web --path=. + +Other web servers, such as Apache, should also serve these files correctly +without any extra configuration. + +(Specifically, the response must have headers +:code:`Content-Type: application/json` and :code:`Content-Encoding: gzip`.) + +Log Locations +============= +Log locations are configured along with normal Django settings in +:code:`stackviz/settings.py`. Several different types of logs are rendered by +StackViz: + +* Tempest (`testr` repositories): :code:`./`, :code:`/opt/stack/tempest/` +* DevStack: *TODO* +* Dstat: *TODO* diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..8852fdd --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,75 @@ +# -*- coding: 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. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + #'sphinx.ext.intersphinx', + 'oslosphinx' +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'stackviz' +copyright = u'2013, OpenStack Foundation' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Foundation', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..1728a61 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,4 @@ +============ +Contributing +============ +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..687c0c0 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,25 @@ +.. stackviz documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to stackviz's documentation! +======================================================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + readme + installation + usage + contributing + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/doc/source/installation.rst b/doc/source/installation.rst new file mode 100644 index 0000000..ac716a2 --- /dev/null +++ b/doc/source/installation.rst @@ -0,0 +1,12 @@ +============ +Installation +============ + +At the command line:: + + $ pip install stackviz + +Or, if you have virtualenvwrapper installed:: + + $ mkvirtualenv stackviz + $ pip install stackviz diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/doc/source/usage.rst b/doc/source/usage.rst new file mode 100644 index 0000000..7d68065 --- /dev/null +++ b/doc/source/usage.rst @@ -0,0 +1,7 @@ +======== +Usage +======== + +To use stackviz in a project:: + + import stackviz