Merge pull request #213 from jacebrowning/release/v1.1

Release v1.1

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Revision History
 
+## 1.1 (2017/01/09)
+
+- Added '--strict-child-check' option to ensure links from every child document. 
+
 ## 1.0.2 (2016/06/08)
 
 - Moved the documentation to [ReadTheDocs](http://doorstop.readthedocs.io).

Makefile

@@ -65,7 +65,7 @@ DEPENDS_CI := $(ENV)/.depends-ci
 DEPENDS_DEV := $(ENV)/.depends-dev
 ALL := $(ENV)/.all
 
-# Main Targets #################################################################
+# MAIN TASKS ###################################################################
 
 .PHONY: all
 all: depends $(ALL)
@@ -76,7 +76,19 @@ $(ALL): $(SOURCES) $(YAML)
 .PHONY: ci
 ci: doorstop pep8 pep257 test tests tutorial
 
-# Development Installation #####################################################
+.PHONY: doorstop
+doorstop: env
+	$(BIN)/doorstop --warn-all --error-all --quiet
+
+.PHONY: gui
+gui: env
+	$(BIN)/doorstop-gui
+
+.PHONY: serve
+serve: env
+	$(SUDO) $(BIN)/doorstop-server --debug --launch --port 80
+
+# PROJECT DEPENDENCIES #########################################################
 
 .PHONY: env
 env: .virtualenv $(EGG_INFO)
@@ -102,24 +114,56 @@ $(DEPENDS_CI): Makefile
 .PHONY: depends-dev
 depends-dev: env Makefile $(DEPENDS_DEV)
 $(DEPENDS_DEV): Makefile
-	$(PIP) install --upgrade pip pep8radius pygments docutils readme pdoc mkdocs markdown wheel
+	$(PIP) install --upgrade pip pep8radius pygments docutils readme pdoc mkdocs markdown wheel twine
 	touch $(DEPENDS_DEV)  # flag to indicate dependencies are installed
 
-# Development Usage ############################################################
+# CHECKS #######################################################################
 
-.PHONY: doorstop
-doorstop: env
-	$(BIN)/doorstop --warn-all --error-all --quiet
+.PHONY: check
+check: pep8 pep257 pylint
 
-.PHONY: gui
-gui: env
-	$(BIN)/doorstop-gui
+.PHONY: pep8
+pep8: depends-ci
+# E501: line too long (checked by PyLint)
+	$(PEP8) $(PACKAGE) --ignore=E501
 
-.PHONY: serve
-serve: env
-	$(SUDO) $(BIN)/doorstop-server --debug --launch --port 80
+.PHONY: pep257
+pep257: depends-ci
+	$(PEP257) $(PACKAGE)
+
+.PHONY: pylint
+pylint: depends-ci
+	$(PYLINT) $(PACKAGE) --rcfile=.pylintrc
+
+.PHONY: fix
+fix: depends-dev
+	$(PEP8RADIUS) --docformatter --in-place
 
-# Documentation ################################################################
+# TESTS ########################################################################
+
+.PHONY: test
+test: depends-ci .clean-test
+	$(NOSE) --config=.noserc
+ifndef TRAVIS
+	$(COVERAGE) html --directory htmlcov --fail-under=$(UNIT_TEST_COVERAGE)
+endif
+
+.PHONY: tests
+tests: depends-ci .clean-test
+	TEST_INTEGRATION=1 $(NOSE) --config=.noserc --cover-package=$(PACKAGE) -xv
+ifndef TRAVIS
+	$(COVERAGE) html --directory htmlcov --fail-under=$(INTEGRATION_TEST_COVERAGE)
+endif
+
+.PHONY: tutorial
+tutorial: env
+	$(PYTHON) $(PACKAGE)/cli/test/test_tutorial.py
+
+.PHONY: read-coverage
+read-coverage:
+	$(OPEN) htmlcov/index.html
+
+# DOCUMENTATION ################################################################
 
 .PHONY: doc
 doc: readme verify-readme uml apidocs mkdocs
@@ -184,53 +228,62 @@ mkdocs: depends-dev site/index.html
 site/index.html: mkdocs.yml docs/*.md
 	$(MKDOCS) build --clean --strict
 
-# Static Analysis ##############################################################
+# BUILD ########################################################################
 
-.PHONY: check
-check: pep8 pep257 pylint
+PYINSTALLER := $(BIN)/pyinstaller
+PYINSTALLER_MAKESPEC := $(BIN)/pyi-makespec
 
-.PHONY: pep8
-pep8: depends-ci
-# E501: line too long (checked by PyLint)
-	$(PEP8) $(PACKAGE) --ignore=E501
+DIST_FILES := dist/*.tar.gz dist/*.whl
+EXE_FILES := dist/$(PROJECT).*
 
-.PHONY: pep257
-pep257: depends-ci
-	$(PEP257) $(PACKAGE)
+.PHONY: dist
+dist: depends-dev $(DIST_FILES)
+$(DIST_FILES): $(MODULES) README.rst CHANGELOG.rst
+	rm -f $(DIST_FILES)
+	$(PYTHON) setup.py check --restructuredtext --strict --metadata
+	$(PYTHON) setup.py sdist
+	$(PYTHON) setup.py bdist_wheel
 
-.PHONY: pylint
-pylint: depends-ci
-	$(PYLINT) $(PACKAGE) --rcfile=.pylintrc
+%.rst: %.md
+	pandoc -f markdown_github -t rst -o $@ $<
 
-.PHONY: fix
-fix: depends-dev
-	$(PEP8RADIUS) --docformatter --in-place
+.PHONY: exe
+exe: depends-dev $(EXE_FILES)
+$(EXE_FILES): $(MODULES) $(PROJECT).spec
+	# For framework/shared support: https://github.com/yyuu/pyenv/wiki
+	$(PYINSTALLER) $(PROJECT).spec --noconfirm --clean
 
-# Testing ######################################################################
+$(PROJECT).spec:
+	$(PYINSTALLER_MAKESPEC) $(PACKAGE)/__main__.py --onefile --windowed --name=$(PROJECT)
 
-.PHONY: test
-test: depends-ci .clean-test
-	$(NOSE) --config=.noserc
-ifndef TRAVIS
-	$(COVERAGE) html --directory htmlcov --fail-under=$(UNIT_TEST_COVERAGE)
-endif
+# RELEASE ######################################################################
 
-.PHONY: tests
-tests: depends-ci .clean-test
-	TEST_INTEGRATION=1 $(NOSE) --config=.noserc --cover-package=$(PACKAGE) -xv
-ifndef TRAVIS
-	$(COVERAGE) html --directory htmlcov --fail-under=$(INTEGRATION_TEST_COVERAGE)
-endif
+TWINE := $(BIN)/twine
 
-.PHONY: tutorial
-tutorial: env
-	$(PYTHON) $(PACKAGE)/cli/test/test_tutorial.py
+.PHONY: register
+register: dist ## Register the project on PyPI
+	@ echo NOTE: your project must be registered manually
+	@ echo https://github.com/pypa/python-packaging-user-guide/issues/263
+	# TODO: switch to twine when the above issue is resolved
+	# $(TWINE) register dist/*.whl
 
-.PHONY: read-coverage
-read-coverage:
-	$(OPEN) htmlcov/index.html
+.PHONY: upload
+upload: .git-no-changes register ## Upload the current version to PyPI
+	$(TWINE) upload dist/*
+	$(OPEN) https://pypi.python.org/pypi/$(PROJECT)
+
+.PHONY: .git-no-changes
+.git-no-changes:
+	@ if git diff --name-only --exit-code;        \
+	then                                          \
+		echo Git working copy is clean...;        \
+	else                                          \
+		echo ERROR: Git working copy is dirty!;   \
+		echo Commit your changes and try again.;  \
+		exit -1;                                  \
+	fi;
 
-# Cleanup ######################################################################
+# CLEANUP ######################################################################
 
 .PHONY: clean
 clean: .clean-dist .clean-test .clean-doc .clean-build
@@ -268,49 +321,10 @@ clean-all: clean clean-env .clean-workspace
 .clean-workspace:
 	rm -rf *.sublime-workspace
 
-# Release ######################################################################
-
-.PHONY: register-test
-register-test: doc
-	$(PYTHON) setup.py register --strict --repository https://testpypi.python.org/pypi
-
-.PHONY: upload-test
-upload-test: register-test
-	$(PYTHON) setup.py sdist upload --repository https://testpypi.python.org/pypi
-	$(PYTHON) setup.py bdist_wheel upload --repository https://testpypi.python.org/pypi
-	$(OPEN) https://testpypi.python.org/pypi/$(PROJECT)
-
-.PHONY: register
-register: doc
-	$(PYTHON) setup.py register --strict
-
-.PHONY: upload
-upload: .git-no-changes register
-	$(PYTHON) setup.py sdist upload
-	$(PYTHON) setup.py bdist_wheel upload
-	$(OPEN) https://pypi.python.org/pypi/$(PROJECT)
-
-.PHONY: .git-no-changes
-.git-no-changes:
-	@ if git diff --name-only --exit-code;        \
-	then                                          \
-		echo Git working copy is clean...;        \
-	else                                          \
-		echo ERROR: Git working copy is dirty!;   \
-		echo Commit your changes and try again.;  \
-		exit -1;                                  \
-	fi;
-
-# System Installation ##########################################################
-
-.PHONY: develop
-develop:
-	$(SYS_PYTHON) setup.py develop
+# HELP #########################################################################
 
-.PHONY: install
-install:
-	$(SYS_PYTHON) setup.py install
+.PHONY: help
+help: all
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-30s\033[0m %s\n", $$1, $$2}'
 
-.PHONY: download
-download:
-	$(SYS_PYTHON) -m pip install $(PROJECT)
+.DEFAULT_GOAL := help

README.md

@@ -1,18 +1,19 @@
-**STATUS:** As of the 1.0 release, this project is no longer under active development. I still plan on accepting any passing pull requests to become part of future 2.x releases.
+**STATUS:** As of the 1.0 release, this project is no longer under active development. Passing pull requests will be considered for future 1.x and 2.x releases.
 
 -----
 
-# Doorstop
-
 [![Build Status](http://img.shields.io/travis/jacebrowning/doorstop/master.svg)](https://travis-ci.org/jacebrowning/doorstop)
 [![Coverage Status](http://img.shields.io/coveralls/jacebrowning/doorstop/master.svg)](https://coveralls.io/r/jacebrowning/doorstop)
 [![Scrutinizer Code Quality](http://img.shields.io/scrutinizer/g/jacebrowning/doorstop.svg)](https://scrutinizer-ci.com/g/jacebrowning/doorstop/?branch=master)
 [![PyPI Version](http://img.shields.io/pypi/v/Doorstop.svg)](https://pypi.python.org/pypi/Doorstop)
 [![PyPI Downloads](http://img.shields.io/pypi/dm/Doorstop.svg)](https://pypi.python.org/pypi/Doorstop)
 
+# Overview
+
 Doorstop manages the storage of textual requirements alongside source code in version control.
 
-<img align="right" width="200" src="https://raw.githubusercontent.com/jacebrowning/doorstop/develop/docs/images/logo-black-white.png"/>
+<img align="left" width="140" src="https://raw.githubusercontent.com/jacebrowning/doorstop/develop/docs/images/logo-black-white.png"/>
+
 When a project utilizes this tool, each linkable item (requirement, test case, etc.) is stored as a YAML file in a designated directory. The items in each directory form a document. The relationship between documents forms a tree hierarchy. Doorstop provides mechanisms for modifying this tree, validating item traceability, and publishing documents in several formats.
 
 Additional reading:
@@ -21,7 +22,7 @@ Additional reading:
 - talks: [GRDevDay](https://speakerdeck.com/jacebrowning/doorstop-requirements-management-using-python-and-version-control), [BarCamp](https://speakerdeck.com/jacebrowning/strip-searched-a-rough-introduction-to-requirements-management)
 - sample: [Generated HTML](http://jacebrowning.github.io/doorstop/index.html)
 
-# Getting Started
+# Setup
 
 ## Requirements
 
@@ -30,7 +31,7 @@ Additional reading:
 
 ## Installation
 
-Doorstop can be installed with pip:
+Install Doorstop with pip:
 
 ```
 $ pip install doorstop
@@ -58,15 +59,15 @@ $ python
 >>> doorstop.__version__
 ```
 
-# Basic Usage
+# Usage
 
 Switch to an existing version control working directory, or create one:
 
 ```
 $ git init .
 ```
 
-## Create a document
+## Create documents
 
 Create a new parent requirements document:
 
@@ -82,7 +83,7 @@ $ doorstop add SRD
 $ doorstop add SRD
 ```
 
-## Links items
+## Link items
 
 Create a child document to link to the parent:
 

docs/cli/validation.md

@@ -6,3 +6,11 @@ To check a document hierarchy for consistency, run the main command:
 $ doorstop
 valid tree: REQ <- [ TST ]
 ```
+
+## Links
+
+To confirm that every item in a document links to its parents:
+
+```sh
+$ doorstop --strict-child-check
+```

doorstop/__init__.py

@@ -3,7 +3,7 @@
 import sys
 
 __project__ = 'Doorstop'
-__version__ = '1.0.2'
+__version__ = '1.1'
 
 CLI = 'doorstop'
 GUI = 'doorstop-gui'

doorstop/cli/main.py

@@ -52,6 +52,8 @@ def main(args=None):  # pylint: disable=R0915
                         help="do not validate external file references")
     parser.add_argument('-C', '--no-child-check', action='store_true',
                         help="do not validate child (reverse) links")
+    parser.add_argument('-Z', '--strict-child-check', action='store_true',
+                        help="require child (reverse) links from every document")
     parser.add_argument('-S', '--no-suspect-check', action='store_true',
                         help="do not check for suspect links")
     parser.add_argument('-W', '--no-review-check', action='store_true',

doorstop/cli/test/__init__.py

@@ -7,7 +7,7 @@
 from doorstop import settings
 
 ROOT = os.path.join(os.path.dirname(__file__), '..', '..', '..')
-REQS = os.path.join(ROOT, 'docs', 'reqs')
+REQS = os.path.join(ROOT, 'reqs')
 TUTORIAL = os.path.join(REQS, 'tutorial')
 FILES = os.path.join(os.path.dirname(__file__), 'files')
 

doorstop/cli/test/test_all.py

@@ -230,7 +230,7 @@ class TestReorder(unittest.TestCase):
     @classmethod
     def setUpClass(cls):
         cls.prefix = 'tut'
-        cls.path = os.path.join('docs', 'reqs', 'tutorial', 'index.yml')
+        cls.path = os.path.join('reqs', 'tutorial', 'index.yml')
 
     def tearDown(self):
         common.delete(self.path)

doorstop/cli/utilities.py

@@ -90,6 +90,8 @@ def configure_settings(args):
         settings.CHECK_REF = args.no_ref_check is False
     if args.no_child_check is not None:
         settings.CHECK_CHILD_LINKS = args.no_child_check is False
+    if args.strict_child_check is not None:
+        settings.CHECK_CHILD_LINKS_STRICT = args.strict_child_check is True
     if args.no_suspect_check is not None:
         settings.CHECK_SUSPECT_LINKS = args.no_suspect_check is False
     if args.no_review_check is not None: