docs to sphinx; githooks; rpm build fix

.gitignore

@@ -28,3 +28,11 @@ pip-log.txt
 
 # coveralls code coverage
 .coverage
+
+# sphinx docs
+_build
+_static
+_templates
+
+# rpm build files
+tmp/

Makefile

@@ -13,7 +13,7 @@ PACKAGE = status-report-$(VERSION)
 DOCS = $(TMP)/$(PACKAGE)/docs
 EXAMPLES = $(TMP)/$(PACKAGE)/examples
 CSS = --stylesheet=style.css --link-stylesheet
-FILES = LICENSE README \
+FILES = LICENSE README.rst \
 		Makefile status-report.spec \
 		docs examples source
 
@@ -23,13 +23,17 @@ endif
 
 all: push clean
 
+# Looking for HTML docs? Could copy them too or just check out http://status-report.readthedocs.org/
+# To build locally; cd docs; make html
+#rst2man README | gzip > $(DOCS)/status-report.1.gz
+#rst2html README $(CSS) > $(DOCS)/index.html
+#rst2man $(DOCS)/notes.rst | gzip > $(DOCS)/status-report-notes.1.gz
+#rst2html $(DOCS)/notes.rst $(CSS) > $(DOCS)/notes.html
+
 build:
 	mkdir -p $(TMP)/{SOURCES,$(PACKAGE)}
 	cp -a $(FILES) $(TMP)/$(PACKAGE)
-	rst2man README | gzip > $(DOCS)/status-report.1.gz
-	rst2html README $(CSS) > $(DOCS)/index.html
-	rst2man $(DOCS)/notes.rst | gzip > $(DOCS)/status-report-notes.1.gz
-	rst2html $(DOCS)/notes.rst $(CSS) > $(DOCS)/notes.html
+	cd docs && make man SPHINXOPTS=-Q && gzip -c _build/man/status-report.1 > $(DOCS)/status-report.1.gz
 
 tarball: build
 	cd $(TMP) && tar cfj SOURCES/$(PACKAGE).tar.bz2 $(PACKAGE)

README.rst

@@ -17,22 +17,15 @@
 
 .. image:: https://pypip.in/license/status_report/badge.svg
     :target: https://pypi.python.org/pypi/status_report/
-    :alt: License
 
 .. image:: https://landscape.io/github/psss/status-report/master/landscape.svg
     :target: https://landscape.io/github/psss/status-report/master
-    :alt: Code Health
 
 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     Generate status report stats for selected date range
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-:Manual section: 1
-:Manual group: User Commands
-:Date: April 2015
-
-
 DESCRIPTION
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 Comfortably generate status report stats (e.g. list of committed
@@ -53,6 +46,25 @@ Generate stats for the last week::
 See status-report --help for complete list of available stats.
 
 
+INSTALLATION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Install directly from Fedora/Copr repository or use PIP::
+
+    # Basic dependencies for buiding/installing pip packages
+    sudo yum install gcc krb5-devel
+    sudo yum install python-devel python-pip python-virtualenv
+
+    # Upgrade to the latest pip/setup/virtualenv installer code
+    sudo pip install -U pip setuptools virtualenv
+
+    # Install into a python virtual environment (OPTIONAL)
+    virtualenv --no-site-packages ~/virtenv_statusreport
+    source ~/virtenv_statusreport/bin/activate
+
+    # Install status_report (sudo required if not in a virtualenv)
+    pip install status_report
+
+
 CONFIGURATION
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 The config file ~/.status-report is used to store both general
@@ -87,41 +99,25 @@ settings and configuration of individual reports::
 
 See also examples link for some more inspiration.
 
-QUICK INSTALL (pip)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-sudo yum install gcc krb5-devel
-virtualenv --no-site-packages ~/virtenv_statusreport
-source ~/virtenv_statusreport/bin/activate
-pip install -U pip setuptools
-pip install status_report
 
 DOCKER INSTALL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Fedora: https://fedoraproject.org/wiki/Getting_started_with_docker
-Feodra: https://fedoraproject.org/wiki/Docker
+To build and execute in a docker container, run::
 
-RUN TESTS (pytest)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-pip install pytest
-py.test source/tests
+    make run_docker
 
-INSTALLATION
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Install directly from Fedora/Copr repository or use PIP::
+See LINKS section below for more docker resources.
 
-    # Basic dependencies for buiding/installing pip packages
-    sudo yum install gcc krb5-devel
-    sudo yum install python-devel python-pip python-virtualenv
 
-    # Upgrade to the latest pip/setup/virtualenv installer code
-    sudo pip install -U pip setuptools virtualenv
-
-    # Install into a python virtual environment (OPTIONAL)
-    virtualenv --no-site-packages ~/virtenv_statusreport
-    source ~/virtenv_statusreport/bin/activate
+GIT COMMIT HOOKS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If you're planning to make commits to this project, please enable
+the following git hooks::
 
-    # Install status_report (sudo required if not in a virtualenv)
-    pip install status_report
+    # UPDATE according to the correct absolute git path
+    PATH = ~/status-report/git-hooks
+    ln -s $(PATH)/pre-commit.py .git/hooks/pre-commit
+    ln -s $(PATH)/commit-msg.py .git/hooks/commit-msg
 
 
 TESTS
@@ -157,6 +153,10 @@ https://github.com/psss/status-report
 PIP repo:
 https://pypi.python.org/pypi/status_report/
 
+Docker Guides:
+https://fedoraproject.org/wiki/Getting_started_with_docker
+https://fedoraproject.org/wiki/Docker
+
 
 AUTHORS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

docs/Makefile

@@ -0,0 +1,53 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = _build
+
+# User-friendly check for sphinx-build
+ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+endif
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest coverage gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+
+clean:
+	rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."