From 26796f6985ec52216a0e05e4b995d1c1e7c4d597 Mon Sep 17 00:00:00 2001
From: Frank Sachsenheim <funkyfuture@riseup.net>
Date: Wed, 4 Oct 2017 20:22:34 +0200
Subject: [PATCH 1/3] Makefile: Makes PHONY statements more maintainable.

---
 Makefile | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/Makefile b/Makefile
index a20df8f39..6e07a8c05 100644
--- a/Makefile
+++ b/Makefile
@@ -1,8 +1,5 @@
 PYTHON ?= python
 
-.PHONY: all style-check type-check clean clean-pyc clean-patchfiles clean-backupfiles \
-        clean-generated pylint reindent test covertest build
-
 DONT_CHECK = -i .ropeproject \
              -i .tox \
              -i build \
@@ -35,33 +32,42 @@ DONT_CHECK = -i .ropeproject \
              -i tests/typing_test_data.py \
              -i utils/convert.py
 
+.PHONY: all
 all: clean-pyc clean-backupfiles style-check type-check test
 
+.PHONY: style-check
 style-check:
 	@PYTHONWARNINGS=all $(PYTHON) utils/check_sources.py $(DONT_CHECK) .
 
+.PHONY: type-check
 type-check:
 	mypy sphinx/
 
+.PHONY: clean
 clean: clean-pyc clean-pycache clean-patchfiles clean-backupfiles clean-generated clean-testfiles clean-buildfiles clean-mypyfiles
 
+.PHONY: clean-pyc
 clean-pyc:
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
 
+.PHONY: clean-pycache
 clean-pycache:
 	find . -name __pycache__ -exec rm -rf {} +
 
+.PHONY: clean-patchfiles
 clean-patchfiles:
 	find . -name '*.orig' -exec rm -f {} +
 	find . -name '*.rej' -exec rm -f {} +
 
+.PHONY: clean-backupfiles
 clean-backupfiles:
 	find . -name '*~' -exec rm -f {} +
 	find . -name '*.bak' -exec rm -f {} +
 	find . -name '*.swp' -exec rm -f {} +
 	find . -name '*.swo' -exec rm -f {} +
 
+.PHONY: clean-generated
 clean-generated:
 	find . -name '.DS_Store' -exec rm -f {} +
 	rm -rf Sphinx.egg-info/
@@ -70,32 +76,41 @@ clean-generated:
 	rm -f utils/*3.py*
 	rm -f utils/regression_test.js
 
+.PHONY: clean-testfiles
 clean-testfiles:
 	rm -rf tests/.coverage
 	rm -rf tests/build
 	rm -rf .tox/
 	rm -rf .cache/
 
+.PHONY: clean-buildfiles
 clean-buildfiles:
 	rm -rf build
 
+.PHONY: clean-mypyfiles
 clean-mypyfiles:
 	rm -rf .mypy_cache/
 
+.PHONY: pylint
 pylint:
 	@pylint --rcfile utils/pylintrc sphinx
 
+.PHONY: reindent
 reindent:
 	@$(PYTHON) utils/reindent.py -r -n .
 
+.PHONY: test
 test:
 	@cd tests; $(PYTHON) run.py --ignore py35 -v $(TEST)
 
+.PHONY: test-async
 test-async:
 	@cd tests; $(PYTHON) run.py -v $(TEST)
 
+.PHONY: covertest
 covertest:
 	@cd tests; $(PYTHON) run.py -v --cov=sphinx --junitxml=.junit.xml $(TEST)
 
+.PHONY: build
 build:
 	@$(PYTHON) setup.py build

From b2959a91c51594560fb7342261e23b9ce9630d37 Mon Sep 17 00:00:00 2001
From: Frank Sachsenheim <funkyfuture@riseup.net>
Date: Wed, 4 Oct 2017 20:31:50 +0200
Subject: [PATCH 2/3] Makefile: Adds a target to build docs from the root dir.

---
 CONTRIBUTING.rst | 3 +--
 Makefile         | 7 +++++++
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 4438e2838..5b9e38db5 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -126,8 +126,7 @@ These are the basic steps needed to start developing on Sphinx.
 
    * Build the documentation and check the output for different builders::
 
-       cd doc
-       make clean html latexpdf
+       make docs target="clean html latexpdf"
 
    * Run code style checks and type checks (type checks require mypy)::
 
diff --git a/Makefile b/Makefile
index 6e07a8c05..5257b2ad5 100644
--- a/Makefile
+++ b/Makefile
@@ -114,3 +114,10 @@ covertest:
 .PHONY: build
 build:
 	@$(PYTHON) setup.py build
+
+.PHONY: docs
+docs:
+ifndef target
+	  $(info You need to give a provide a target variable, e.g. `make docs target=html`.)
+endif
+	  $(MAKE) -C doc $(target)

From 990de5799a1c6b6f7767ad93ec003c3910aac723 Mon Sep 17 00:00:00 2001
From: Frank Sachsenheim <funkyfuture@riseup.net>
Date: Wed, 4 Oct 2017 22:32:12 +0200
Subject: [PATCH 3/3] Adds a note about passing args to pytest.

---
 CONTRIBUTING.rst | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 5b9e38db5..eca6a01ac 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -124,6 +124,11 @@ These are the basic steps needed to start developing on Sphinx.
 
        PYTHONWARNINGS=all make test
 
+   * Arguments to pytest can be passed via tox, e.g. in order to run a
+     particular test::
+
+       tox -e py27 tests/test_module.py::test_new_feature
+
    * Build the documentation and check the output for different builders::
 
        make docs target="clean html latexpdf"