Fancy-pants Sphinx docs

docs/Guardfile

@@ -0,0 +1,12 @@
+#!/usr/bin/env python
+from livereload.task import Task
+from livereload.compiler import shell
+
+# You may have a different path, e.g. _source/
+Task.add('*.rst', shell('make html'))
+Task.add('*/*.rst', shell('make html'))
+Task.add('_static/*.css', shell('make html'))
+Task.add('Makefile', shell('make html'))
+Task.add('Guardfile', shell('make html'))
+Task.add('conf.py', shell('make html'))
+Task.add('../better', shell('make clean html'))

docs/Makefile

@@ -0,0 +1,23 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+BUILDDIR      = _build
+
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(SPHINXOPTS) .
+
+.PHONY: clean html all livehtml browsehtml
+
+all: clean html
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+livehtml: html
+	livereload $(BUILDDIR)/html -p 33233
+
+browsehtml: html
+	livereload -b $(BUILDDIR)/html -p 33233

docs/_build/.gitignore

@@ -0,0 +1,2 @@
+*
+!.gitignore

docs/conf.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+
+from better import better_theme_path
+print better_theme_path
+
+extensions = []
+templates_path = []
+source_suffix = '.rst'
+master_doc = 'index'
+
+project = u'pivotal_tools'
+copyright = u'2013 Jonathan Tushman and pivotal_tools contributors'
+# The short X.Y version.
+version = '0.11'
+# The full version, including alpha/beta/rc tags.
+release = '0.11'
+exclude_patterns = ['_build']
+pygments_style = 'sphinx'
+
+html_theme_path = [better_theme_path]
+html_theme = 'better'
+html_theme_options = {
+    'inlinecss': """
+    """,
+    'cssfiles': [],
+    'scriptfiles': [],
+    'enablesidebarsearch': False,
+    'showrelbartop': False,
+    'showrelbarbottom': False,
+    'showheader': False,
+}
+html_title = "{} {}".format(project, release)
+html_short_title = "Home"
+
+html_logo = None
+html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = []
+html_show_sphinx = True
+html_show_copyright = True
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pivotal_toolsdoc'

docs/index.rst

@@ -0,0 +1,140 @@
+pivotal_tools v0.11
+===================
+
+pivotal_tools is a geeky command-line interface with additional scrum, planning
+poker, and changelog generation features.
+
+`Blog post on its usage`_
+
+.. _Blog post on its usage: http://jtushman.github.io/blog/2013/08/15/introducing-pivotal-tools/
+
+
+Installation
+------------
+
+::
+
+    pip install pivotal_tools
+
+Add :envvar:`PIVOTAL_TOKEN` to your environment.
+
+If you use zsh, you could put it in :file:`~/.zshenv`, like so::
+
+    export PIVOTAL_TOKEN='your token'
+
+Also make sure in your pivotal project settings that you have "Allow API
+Access" checked (which is currently the default behavior).
+
+Usage
+-----
+
+Options accepted by all commands
+""""""""""""""""""""""""""""""""
+
+All commands take the following options:
+
+:option:`--project-index`
+    If you have multiple projects, this is the index that the project shows up
+    in my prompt. This is useful if you do not want to be prompted, and then
+    you can pipe the output. Passing this parameter will make everything
+    faster.
+
+Commands
+""""""""
+
+changelog
+^^^^^^^^^
+
+List out projects stories that are delivered or finished (not accepted)
+
+show_stories
+^^^^^^^^^^^^
+
+Lists all stories for a given project (will prompt you if not specified).
+
+:option:`--for`
+    Filter by the given user name.
+
+:option:`--number`
+    Number of stories to show. Defaults to 20.
+
+show_story <story_id>
+^^^^^^^^^^
+
+::
+
+    pivotal_tools show_story <story_id>
+
+Show the details for a given story.
+
+browser_open <story_id>
+^^^^^^^^^^^^
+
+::
+
+    pivotal_tools browser_open <story_id>
+
+Will open the given story in a browser.
+
+scrum
+^^^^^
+
+::
+
+    pivotal_tools scrum
+
+Will list stories and bugs that team members are working on. Grouped by team
+member.
+
+poker or planning
+^^^^^^^^^^^^^^^^^
+
+::
+
+    pivotal_tools poker
+    pivotal_tools planning  # equivalent
+
+Help to facilitate a planning poker session.
+
+create
+^^^^^^
+
+::
+
+    pivotal_tools create feature
+    pivotal_tools create bug
+    pivotal_tools create chore
+
+Create a story.
+
+<verb> story <story_id>
+^^^^^^^^^^^^
+
+::
+
+    pivotal_tools start story <story_id>
+    pivotal_tools finish story <story_id>
+    pivotal_tools deliver story <story_id>
+    pivotal_tools accept story <story_id>
+    pivotal_tools reject story <story_id>
+
+Change the state of a story.
+
+::
+
+    Usage:
+    pivotal_tools changelog [--project-index=<pi>]
+    pivotal_tools show_stories [--project-index=<pi>] [--for=<user_name>] [--number=<number_of_stories>]
+    pivotal_tools show_story <story_id> [--project-index=<pi>]
+    pivotal_tools browser_open <story_id> [--project-index=<pi>]
+    pivotal_tools scrum [--project-index=<pi>]
+    pivotal_tools poker [--project-index=<pi>]
+    pivotal_tools planning [--project-index=<pi>]
+    pivotal_tools create (feature|bug|chore) <title> [<description>] [--project-index=<pi>]
+    pivotal_tools (start|finish|deliver|accept|reject) story <story_id> [--project-index=<pi>]
+
+    Options:
+    -h --help             Show this screen.
+    --for=<user_name>     Username, or initials
+    --project-index=<pi>  If you have multiple projects, this is the index that the project shows up in my prompt
+                            This is useful if you do not want to be prompted, and then you can pipe the output

docs/requirements.txt

@@ -0,0 +1,8 @@
+# Requirements for building the docs
+Jinja2==2.7.1
+MarkupSafe==0.18
+Pygments==1.6
+Sphinx==1.1.3
+docutils==0.11
+sphinx-better-theme==0.1
+wsgiref==0.1.2

docs/requirements_livereload.txt

@@ -0,0 +1,12 @@
+# Requirements for building the docs with support livereload with
+# 'make livehtml' and 'make browsehtml'
+Jinja2==2.7.1
+MarkupSafe==0.18
+Pygments==1.6
+Sphinx==1.1.3
+docopt==0.6.1
+docutils==0.11
+livereload==1.0.1
+sphinx-better-theme==0.1
+tornado==3.1
+wsgiref==0.1.2