From 345b1e41cff4421b317fa24d6b5b966c3fb704aa Mon Sep 17 00:00:00 2001
From: Ruslan Kamaldinov <rkamaldinov@mirantis.com>
Date: Sun, 26 Jan 2014 21:17:17 +0400
Subject: [PATCH] Update documentation
The goal of this patch is to setup infrastructure and organization
of docs in the project.
Changes:
* Modified README to be similar to other OS projects
* Added project description to the index page
* Added install and run guide
Note(1):
These docs will be auto-published to http://ci.openstack.org/storyboard
after each merge very soon.
Note(2):
To build docs locally run in console:
$ tox -e docs
and open doc/build/html/index.html
Change-Id: I08b57117f90f3e4614bfa5c47020e40a6c26ff65
---
CONTRIBUTING.rst | 51 ++++++++---
README.rst | 137 +++++------------------------
doc/source/index.rst | 39 ++++++--
doc/source/install/development.rst | 9 ++
doc/source/install/index.rst | 11 +++
doc/source/install/manual.rst | 53 +++++++++++
doc/source/installation.rst | 12 ---
doc/source/readme.rst | 1 -
8 files changed, 163 insertions(+), 150 deletions(-)
create mode 100644 doc/source/install/development.rst
create mode 100644 doc/source/install/index.rst
create mode 100644 doc/source/install/manual.rst
delete mode 100644 doc/source/installation.rst
delete mode 100644 doc/source/readme.rst
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 1552f0e5..83f8fc36 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,17 +1,46 @@
-If you would like to contribute to the development of OpenStack,
-you must follow the steps in the "If you're a developer, start here"
-section of this page:
+.. _contributing:
- http://wiki.openstack.org/HowToContribute
+==========================
+Contributing to Storyboard
+==========================
-Once those steps have been completed, changes to OpenStack
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
+If you're interested in contributing to the Storyboard project,
+the following will help get you started.
- http://wiki.openstack.org/GerritWorkflow
+Contributor License Agreement
+-----------------------------
-Pull requests submitted through GitHub will be ignored.
+.. index::
+ single: license; agreement
-Storyboard uses itself for bug tracking. Bugs should be filed at:
+In order to contribute to the Storyboard project, you need to have
+signed OpenStack's contributor's agreement.
- https://stories.openstack.org
+.. seealso::
+
+ * http://wiki.openstack.org/HowToContribute
+ * http://wiki.openstack.org/CLA
+
+Project Hosting Details
+-------------------------
+
+Bug tracker
+ http://storyboard.openstack.org
+
+Mailing list (prefix subjects with ``[storyboard]`` for faster responses)
+ http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-infra
+
+Wiki
+ https://wiki.openstack.org/wiki/StoryBoard
+
+Code Hosting
+ * https://git.openstack.org/cgit/openstack-infra/storyboard/
+
+ * https://git.openstack.org/cgit/openstack-infra/storyboard-webclient
+
+Code Review
+ https://review.openstack.org/#/q/status:open+AND+(project:openstack-infra/storyboard+OR+project:openstack-infra/storyboard-webclient),n,z
+
+ Please read `GerritWorkflow`_ before sending your first patch for review.
+
+.. _GerritWorkflow: https://wiki.openstack.org/wiki/GerritWorkflow
diff --git a/README.rst b/README.rst
index 19589abd..64a3a7c3 100644
--- a/README.rst
+++ b/README.rst
@@ -1,132 +1,35 @@
-==============================================================
-StoryBoard - A task tracking system for inter-related projects
-==============================================================
+Storyboard
+==========
-StoryBoard is the Django app (leveraging Bootstrap at the presentation layer)
-for task tracking across inter-related projects. It is meant to be suitable
-for OpenStack task tracking.
-
-Features
-========
-
-At this stage, StoryBoard is just a proof-of-concept to see if it's worth
-investing more into developing it.
-
-Current features
-----------------
-
-*Project views*
- Basic project views that let you retrieve the list of tasks for a given
- project, as well as an example of a workflow-oriented view (the 'Triage
- bugs' view). The current POC is is also just a minimal stub of the project
- view feature set.
-
-*Bug tracking*
- Like Launchpad Bugs, StoryBoard implements bugs as stories, with tasks that
- may affect various project/branch combinations. You can currently create
- bugs, tasks for bugs, edit their status, comment on them, etc. The current
- POC is incomplete: it does not do any sort of form client-side validation,
- and is missing search features, pagination, results ordering. This should
- definitely be improved if we go forward with this.
+Storyboard is a task tracker for OpenStack.
-*Feature tracking*
- The equivalent of Launchpad Blueprints, they inherit the same 'story'
- framework as bugs. That means they don't have most of the limitations of
- LP blueprints: you can comment in them, you can have tasks affecting multiple
- projects, you can even have multiple tasks affecting the same project and
- order them !
+-----------------
+Project Resources
+-----------------
-*Project groups*
- Projects can be grouped together arbitrarily, and all 'project' views can
- be reused by project groups. That makes it easy to triage or track all
- tasks for projects within a given OpenStack program.
+Project status, bugs, and blueprints are tracked at:
-*Markdown descriptions and comments*
- Story descriptions and comments can use markdown for richer interaction.
+ http://storyboard.openstack.org
+Source code can be found at:
-Questionable features
----------------------
+ https://git.openstack.org/cgit/openstack-infra/storyboard/
-Some current design choices are questionable and open to discussion:
+Documentation can be found here:
-Priority is set for the whole story
- Instead of each task having their own priority, the story itself has a
- priority. It makes triaging easier, however we may want to be able to have
- tasks with various priorities within a single story...
+ http://ci.openstack.org/storyboard/
-No invalid/wontfix/opinion status
- We delete tasks rather than marking them invalid. On the benefits side, that
- means there is only one way to do it, on the drawbacks side you have to look
- into history to see if a given project task was considered and abandoned...
+Additional resources are linked from the project wiki page:
+ https://wiki.openstack.org/wiki/StoryBoard
-Future features
----------------
+Anyone wishing to contribute to an OpenStack project should
+find plenty of helpful resources here:
-*Subscription*
- Users should be able to subscribe to tasks (and get them in a specific view)
- as well as subscribe to projects (have their own customized project group).
- This lets you easily get customized views for the stuff that happens to
- matters to you, personally.
+ https://wiki.openstack.org/wiki/HowToContribute
-*Gerrit integration*
- StoryBoard should reuse the projects and groups defined for Gerrit. It should
- reflect merges with deeper integration than with LP... potentially forcing
- a 1:1 relationship between tasks and merges (one merge = one task marked
- 'Landed')
+All OpenStack projects use Gerrit for code reviews.
+A good reference for that is here:
-*Development cycle tracking*
- A new tab for StoryBoard, giving you per-cycle and per-milestone views of
- progress. Would replace the need for status.o.o/releasestatus. Cycles and
- milestones could be specified per project, although having a default, common
- set would avoid duplication (and allow cross-project milestone views).
-
-See https://github.com/ttx/storyboard/issues for more feature backlog.
-
-
-Install, test and run
-=====================
-
-Prerequisites
--------------
-
-You'll need the following Python modules installed:
- - django (1.4+)
- - django-openid-auth
- - markdown
- - python-openid
-
-You can get them by running::
-
- pip install -r requirements.txt
-
-Configuration and DB creation
------------------------------
-
-Copy storyboard/local_settings.py.sample to storyboard/local_settings.py
-and change settings there.
-
-Create empty database, create default admin user:
-./manage.py syncdb
-
-
-Basic test using Django development server
-------------------------------------------
-
-Run Django development server:
-./manage.py runserver
-
-Create basic data via the admin interface: http://127.0.0.1:8000/admin,
-using the admin credentials above.
-
-At least:
- * a master branch
- * a release branch
- * a milestone associated with the master branch
- - the milestone also has to have the undefined box checked
- * a project
-
-Then log out and access the application at:
-http://127.0.0.1:8000/
+ https://wiki.openstack.org/wiki/GerritWorkflow
diff --git a/doc/source/index.rst b/doc/source/index.rst
index e60822d1..be6a1c63 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -1,20 +1,41 @@
-.. storyboard 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 Storyboard's documentation!
+======================================
-Welcome to storyboard's documentation!
-========================================================
+Introduction
+============
-Contents:
+StoryBoard is a web application for task tracking across inter-related projects.
+It is meant to be suitable for OpenStack task tracking.
+
+StoryBoard consists of two components:
+ * `Storyboard API service`_ - is a Python application leveraging
+ `Pecan`_/`WSME`_ for REST API layer
+ * `Storyboard Web Client`_ - is an all-javascript webclient for the
+ Storyboard API
+
+
+.. _Pecan: http://pecan.readthedocs.org/en/latest/
+.. _WSME: http://wsme.readthedocs.org/en/latest/
+.. _Storyboard API service: https://git.openstack.org/cgit/openstack-infra/storyboard/
+.. _Storyboard Web Client: https://git.openstack.org/cgit/openstack-infra/storyboard-webclient
+
+
+
+This documentation offers information on how Storyboard works and how to
+contribute to the project.
+
+
+Table of contents
+=================
.. toctree::
:maxdepth: 2
- readme
- installation
+ install/index
contributing
+
Indices and tables
==================
diff --git a/doc/source/install/development.rst b/doc/source/install/development.rst
new file mode 100644
index 00000000..86432865
--- /dev/null
+++ b/doc/source/install/development.rst
@@ -0,0 +1,9 @@
+================================================
+ Installing and Running the Development Version
+================================================
+
+See `webclient readme file`_ for details.
+
+More details will be added later...
+
+.. _webclient readme file: https://git.openstack.org/cgit/openstack-infra/storyboard-webclient/tree/README.md
\ No newline at end of file
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
new file mode 100644
index 00000000..65dc4201
--- /dev/null
+++ b/doc/source/install/index.rst
@@ -0,0 +1,11 @@
+.. _install:
+
+======================
+ Installing Storyboard
+======================
+
+.. toctree::
+ :maxdepth: 2
+
+ development
+ manual
diff --git a/doc/source/install/manual.rst b/doc/source/install/manual.rst
new file mode 100644
index 00000000..46bcfa52
--- /dev/null
+++ b/doc/source/install/manual.rst
@@ -0,0 +1,53 @@
+=====================
+ Installing Manually
+=====================
+
+Installing the API service
+==========================
+
+1. At the command line::
+
+ $ pip install storyboard
+
+
+ Or, if you have virtualenvwrapper installed::
+
+ $ mkvirtualenv storyboard
+ $ pip install storyboard
+
+2. By default Storyboard will use SQLite driver which is suitable only for
+ development mode. Storyboard supports MySQL and PostgreSQL backends.
+ To install MySQL driver execute::
+
+ $ pip install MySQL-python
+
+ To install PostgreSQL driver execute::
+
+ $ pip install psycopg2
+
+3. Edit ``/etc/storyboard/storyboard.conf``. You'll need to modify ``connection``
+ parameter in the ``[database]`` section.
+
+ For MySQL it will look like::
+
+ connection = mysql://root:pass@127.0.0.1:3306/storyboard
+
+4. Migrate database to current state::
+
+ $ storyboard-db-manage --config-file /etc/storyboard/storyboard.conf upgrade head
+
+5. Launch API service::
+
+ $ storyboard-api --config-file /etc/storyboard/storyboard.conf
+
+ .. note::
+
+ Is is recommended to use Apache+mod_wsgi for production installation.
+
+
+Installing the Web Client
+=========================
+
+Web Client is an all-javascript application. It doesn't require any software to
+run. Just grab tarball from http://tarballs.openstack.org/storyboard-webclient,
+unpack it and serve as static files.
\ No newline at end of file
diff --git a/doc/source/installation.rst b/doc/source/installation.rst
deleted file mode 100644
index 89e286ad..00000000
--- a/doc/source/installation.rst
+++ /dev/null
@@ -1,12 +0,0 @@
-============
-Installation
-============
-
-At the command line::
-
- $ pip install storyboard
-
-Or, if you have virtualenvwrapper installed::
-
- $ mkvirtualenv storyboard
- $ pip install storyboard
diff --git a/doc/source/readme.rst b/doc/source/readme.rst
deleted file mode 100644
index a6210d3d..00000000
--- a/doc/source/readme.rst
+++ /dev/null
@@ -1 +0,0 @@
-.. include:: ../../README.rst