From f3848085e1eab0daadb8e2ec66e015471644116a Mon Sep 17 00:00:00 2001 From: Austin Clark Date: Thu, 10 Mar 2016 11:36:04 -0700 Subject: [PATCH] Restructure Stackviz docs This patch changes the format of Stackviz docs so that all information is stored in the appropriate doc/source/ directory rather than all in README.rst. README.rst now just uses the RST include directive to get its text from doc/source/readme.rst. Usage and installation are now in their own RST files for increased modularity, and are included in doc/source/readme.rst. Additional developer documentation has also been created at doc/source/man/ and includes more information on stackviz-export as well as the AngularJS front-end. Change-Id: I1d37194add998cf83a66d380ec7390e31184bdb3 --- CONTRIBUTING.rst | 18 +----- README.rst | 78 +----------------------- doc/source/contributing.rst | 19 +++++- doc/source/index.rst | 23 ++++--- doc/source/installation.rst | 20 +++++-- doc/source/man/index.rst | 28 +++++++++ doc/source/man/stackviz-export.rst | 47 +++++++++++++++ doc/source/man/stackviz-front.rst | 96 ++++++++++++++++++++++++++++++ doc/source/readme.rst | 31 +++++++++- doc/source/usage.rst | 44 +++++++++++++- 10 files changed, 290 insertions(+), 114 deletions(-) create mode 100644 doc/source/man/index.rst create mode 100644 doc/source/man/stackviz-export.rst create mode 100644 doc/source/man/stackviz-front.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 014d617..d0d0928 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,17 +1 @@ -If you would like to contribute to the development of OpenStack, you must -follow the steps in this page: - - http://docs.openstack.org/infra/manual/developers.html - -If you already have a good understanding of how the system works and your -OpenStack accounts are set up, you can skip to the development workflow -section of this documentation to learn how changes to OpenStack should be -submitted for review via the Gerrit tool: - - http://docs.openstack.org/infra/manual/developers.html#development-workflow - -Pull requests submitted through GitHub will be ignored. - -Bugs should be filed on Launchpad, not GitHub: - - https://bugs.launchpad.net/stackviz +.. include:: ./doc/source/contributing.rst diff --git a/README.rst b/README.rst index 220a481..51babe2 100644 --- a/README.rst +++ b/README.rst @@ -1,77 +1 @@ -======== -StackViz -======== -A visualization utility to help analyze the performance of DevStack setup and -Tempest executions. - -Installation - Frontend -======================= -Installation of the frontend requires Node.js and Gulp. On Ubuntu:: - - sudo apt-get install nodejs npm nodejs-legacy - sudo npm install -g gulp - -Then, install the Node modules by running, from the project directory:: - - npm install - -Installation - Processing -========================= -The data processor is a small Python module located in the same source tree. To -install, run:: - - sudo pip install . - -Usage - Development -=================== -A development server can be run as follows:: - - gulp dev - -This will open a web browser and reload code automatically as it changes on the -filesystem. - -If you have subunit and dstat logs, you can create a config.json to display -your runs:: - - stackviz-export -f --dstat app/data/ - -During :code:`gulp dev`, files written to :code:`app/data/` will be -automatically synchronized with the browser. Note that these files will *not* be -copied to :code:`build/` during :code:`gulp prod`, but you can copy them -manually using :code:`gulp data`. - -Usage - Production -================== -The production application can be build using:: - - gulp prod - -The result will be written to :code:`./build` and should be appropriate for -distribution. Note that all files are not required: - -- Directory structure (:code:`js/`, :code:`css/`, :code:`fonts/`, - :code:`images/`): required. -- Static resources (:code:`fonts/`, :code:`images/`): required. -- Core files (:code:`index.html`, :code:`js/main.js`, :code:`css/main.css`): - required unless gzipped versions are used. -- Gzipped versions of core files (:code:`*.gz`): not required, but preferred. - Use instead of plain core files to save on disk usage and bandwidth. -- Source maps (:code:`js/main.js.map`, :code:`js/main.js.map.gz`): only required - for debugging purposes. - -Data should be written to :code:`build/data/` using :code:`stackviz-export` like -above. Note that the static production code generated above is portable, and can -be generated anywhere and copied to another host to be combined with exported -data. - -Testing -======= -* Python tests: :code:`tox -epy27` -* JavaScript unit tests: :code:`gulp unit` -* JavaScript E2E tests: :code:`gulp e2e` - -Roadmap and Planning -==================== -- Planning: https://etherpad.openstack.org/p/stackviz -- Gate integration planning: https://etherpad.openstack.org/p/BKgWlKIjgQ +.. include:: ./doc/source/readme.rst diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1728a61..981fed7 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1,19 @@ -============ Contributing ============ -.. include:: ../../CONTRIBUTING.rst +If you would like to contribute to the development of OpenStack, you must +follow the steps in this page: + + http://docs.openstack.org/infra/manual/developers.html + +If you already have a good understanding of how the system works and your +OpenStack accounts are set up, you can skip to the development workflow +section of this documentation to learn how changes to OpenStack should be +submitted for review via the Gerrit tool: + + http://docs.openstack.org/infra/manual/developers.html#development-workflow + +Pull requests submitted through GitHub will be ignored. + +Bugs should be filed on Launchpad, not GitHub: + + https://bugs.launchpad.net/stackviz diff --git a/doc/source/index.rst b/doc/source/index.rst index 687c0c0..ac03850 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,20 +1,28 @@ -.. 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! +Welcome to Stackviz's documentation! ======================================================== -Contents: +Stackviz is a visualization utility to help analyze the performance of DevStack +setup and Tempest test runs. The following documentation details the procedures +for installing Stackviz on your local machine to view local runs, as well as +how to use Stackviz to view upstream runs. For more information on how +Stackviz runs, see the manual pages. +Local Stackviz: +--------------- .. toctree:: :maxdepth: 2 readme installation usage - contributing + +Manual Pages: +------------- +.. toctree:: + :maxdepth: 1 + + man/* Indices and tables ================== @@ -22,4 +30,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/doc/source/installation.rst b/doc/source/installation.rst index ac716a2..8fdb06b 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,12 +1,20 @@ -============ Installation ============ -At the command line:: +Installation - Frontend +----------------------- +Installation of the frontend requires Node.js and Gulp. On Ubuntu:: - $ pip install stackviz + sudo apt-get install nodejs npm nodejs-legacy + sudo npm install -g gulp -Or, if you have virtualenvwrapper installed:: +Then, install the Node modules by running, from the project directory:: - $ mkvirtualenv stackviz - $ pip install stackviz + npm install + +Installation - Processing +------------------------- +The data processor is a small Python module located in the same source tree. To +install, run:: + + sudo pip install . diff --git a/doc/source/man/index.rst b/doc/source/man/index.rst new file mode 100644 index 0000000..26293fd --- /dev/null +++ b/doc/source/man/index.rst @@ -0,0 +1,28 @@ + +Welcome to Stackviz's Manuals! +======================================================== + +In this directory, you will find detailed documentation describing Stackviz +components and how they work together. + +Stackviz is broken up into two distinct components: a Python processing module +(stackviz/stackviz) and an AngularJS front-end (stackviz/app). Stackviz also +uses Gulp to manage various tasks including building sites and running tests. +For information on each of these components, see their corresponding RST entry. +Below is a listing of each major subdirectory in Stackviz. + +Directories: +------------ +- :code:`./app/`: AngularJS front-end. +- :code:`./doc/`: Stackviz's documentation. +- :code:`./gulp/`: Gulp used for task management. +- :code:`./stackviz/`: Python processing module. +- :code:`./test/`: Unit and e2e tests. + +Documentation for the Python processing module and AngularJS front-end: + +.. toctree:: + :maxdepth: 1 + + stackviz-export + stackviz-front diff --git a/doc/source/man/stackviz-export.rst b/doc/source/man/stackviz-export.rst new file mode 100644 index 0000000..d7144ff --- /dev/null +++ b/doc/source/man/stackviz-export.rst @@ -0,0 +1,47 @@ +=============================================== +Python Data-Processing Module (stackviz-export) +=============================================== + +The main purpose of :code:`stackviz-export` is to parse subunit and dstat logs +in order to generate configuration files for the AngularJS front-end. + +Installation +============ +Once Stackviz has been cloned into a suitable directory, setting up the module +is as simple as:: + + sudo pip install . + +Usage +===== + +:code:`stackviz-export [options] ` + +Where DEST is the output directory of the module. If DEST does not exist, a new +directory will be created. One of the following input options must be chosen: + + **-f, --streamfile FILE** + Specifies a subunit stream file to be used with the exporter. This + argument can be used multiple times to specify additional subunit files. + + **-i, --stdin** + Instructs stackviz-export to read a subunit stream from stdin. + + **-r, --repository REPOSITORY** + Specifies a :code:`.testrepository` to read subunit streams from. This + argument can be used multiple times to specify additional repositories. + +Stackviz also visualizes machine utilization statistics using dstat. To attach +a dstat.csv log to the subunit output, specify the following option: + + **--dstat FILE** + Specifies a csv-formatted dstat log file that corresponds with the + provided subunit stream file. + +Additional options: + + **-h --help** + Print help message. + + **-z --gzip** + Enables gzip compression for data files. diff --git a/doc/source/man/stackviz-front.rst b/doc/source/man/stackviz-front.rst new file mode 100644 index 0000000..e86acb7 --- /dev/null +++ b/doc/source/man/stackviz-front.rst @@ -0,0 +1,96 @@ +=================== +AngularJS Front-end +=================== + +The AngularJS front-end uses config files generated by :code:`stackviz-export` +to display a variety of information regarding test runs. This document breaks +down the various components of the Stackviz Angular app. + +Pages +===== + +---- +Home +---- +:Path: /#/ +:Directive: :code:`./app/views/home.html` +:Controller: :code:`./app/js/controllers/home.js` + +The landing page for Stackviz consists of two elements. The first is a summary +panel that shows statistics for the run including runtime (MM:SS), total number +of tests run, number of failed tests, and number of skipped tests. The button +in the footer of this panel links to the timeline, where individual tests can +be browsed further. The second element is a panel showing all of the failures +for the current run, including the last few lines of their tracebacks. The test +divs here link to their corresponding Test Details page. + +-------- +Timeline +-------- +:Path: /#//timeline?test=/ +:Directive: :code:`./app/views/timeline.html` +:Controller: :code:`./app/js/controllers/timeline.js` + +The Timeline provides an overview of all the tests that were executed as part +of a run. Each lane in the timeline corresponds to one worker thread on the +host machine. Each rectangle in the timeline represents one test. When a +rectangle is selected, the details panel below the timeline is populated with +information about the test. Each test rectangle is also color-coordinated: +green is passing, blue is skipped, and red is failed. + +The details panel below the timeline shows information pertaining to the +current test (it is empty if no test is selected): test class, test module, +which worker executed it, the duration, and start & finish timestamps. The +footer contains a button that links to the test details page for the selected +test. + +------------ +Test Details +------------ +:Path: /#//test-details// +:Directive: :code:`./app/views/test-details.html` +:Controller: :code:`./app/js/controllers/home.js` + +The test details page consists of one panel that displays various log info +from one test. The first tab contains summary information similar to the info +found on the test panel on the timeline. Additional tabs in this panel +are dependent upon the logs that the test kept. Each of these tabs provides +additional information to aid debugging. The most common tabs include: + + **pythonlogging** + Contains logs for API calls that were used in the test. This + log is often quite large, as it contains full headers for every request + at INFO, DEBUG, WARNING, and ERROR levels. To make searching these logs + easier, the test details page has a built in filter for parsing by log + level. In the header of the test details page, the magnifying glass + can be clicked to only show pythonlogging lines that correspond to a + certain level of detail. To find errors in pythonlogging quickly, it is + advisable to only select the WARNING and ERROR levels for display. + + **reason** + Only available for skipped tests. Lists the reason for skipping the test, + usually to avoid triggering an outstanding bug. + + **traceback** + Only available for failed tests. Shows the full traceback of the test + runner's error output when the test failed. This is useful in quickly + isolating the cause of a failure. There can be multiple traceback logs + (e.g. traceback, traceback1) for one test. + +When enough information has been gleaned from more detailed logs, the button +in the panel filter can be used to quickly navigate back to the timeline page. + +Controllers +=========== + +Directives +========== + +Filters +======= + +Services +======== + +Util +==== diff --git a/doc/source/readme.rst b/doc/source/readme.rst index a6210d3..b198e51 100644 --- a/doc/source/readme.rst +++ b/doc/source/readme.rst @@ -1 +1,30 @@ -.. include:: ../../README.rst +======== +StackViz +======== +A visualization utility to help analyze the performance of DevStack setup and +Tempest executions. This repository can be cloned and built to use Stackviz +with local run data. Stackviz is currently in the process of being implemented +upstream (see Roadmap and Planning). To use Stackviz with upstream gate runs, +please see the server deployment project at: + + https://github.com/timothyb89/stackviz-deployer + +.. include:: ./installation.rst + +.. include:: ./usage.rst + +Testing +======= +* Python tests: :code:`tox -epy27` +* JavaScript unit tests: :code:`gulp unit` +* JavaScript E2E tests: :code:`gulp e2e` + +Manuals & Developer Docs +======================== +For more detailed information on how Stackviz works, please see the manuals +located at doc/source/man/ + +Roadmap and Planning +==================== +- Planning: https://etherpad.openstack.org/p/stackviz +- Gate integration planning: https://etherpad.openstack.org/p/BKgWlKIjgQ diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 7d68065..1c1cfa5 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,7 +1,45 @@ -======== Usage ======== -To use stackviz in a project:: +Usage - Development +------------------- +A development server can be run as follows:: - import stackviz + gulp dev + +This will open a web browser and reload code automatically as it changes on the +filesystem. + +If you have subunit and dstat logs, you can create a config.json to display +your runs:: + + stackviz-export -f --dstat app/data/ + +During :code:`gulp dev`, files written to :code:`app/data/` will be +automatically synchronized with the browser. Note that these files will *not* be +copied to :code:`build/` during :code:`gulp prod`, but you can copy them +manually using :code:`gulp data`. + +Usage - Production +------------------ +The production application can be build using:: + + gulp prod + +The result will be written to :code:`./build` and should be appropriate for +distribution. Note that all files are not required: + +- Directory structure (:code:`js/`, :code:`css/`, :code:`fonts/`, + :code:`images/`): required. +- Static resources (:code:`fonts/`, :code:`images/`): required. +- Core files (:code:`index.html`, :code:`js/main.js`, :code:`css/main.css`): + required unless gzipped versions are used. +- Gzipped versions of core files (:code:`*.gz`): not required, but preferred. + Use instead of plain core files to save on disk usage and bandwidth. +- Source maps (:code:`js/main.js.map`, :code:`js/main.js.map.gz`): only required + for debugging purposes. + +Data should be written to :code:`build/data/` using :code:`stackviz-export` like +above. Note that the static production code generated above is portable, and can +be generated anywhere and copied to another host to be combined with exported +data.