Merge pull request #605 from blueyed/docs

Improve docs / qa

Author: blueyed

.travis.yml

@@ -27,12 +27,12 @@ jobs:
 
     # pypy/pypy3: not included with coverage reports (much slower then).
     - python: pypy
-      env: TOXENV=pypy-dj111-sqlite_file
+      env: TOXENV=pypy-dj111-sqlite_file SKIP_COVERAGE=1
     - python: pypy3
-      env: TOXENV=pypy3-dj110-sqlite
+      env: TOXENV=pypy3-dj110-sqlite SKIP_COVERAGE=1
 
     - python: 3.6
-      env: TOXENV=checkqa
+      env: TOXENV=checkqa,docs SKIP_COVERAGE=1
 
     - stage: PyPI Release
       if: tag IS present
@@ -65,8 +65,8 @@ install:
 
   - pip install tox==2.9.1
   - |
-    # Setup coverage tracking, but not with "checkqa" nor "pypy*".
-    if [[ "$TOXENV" != "checkqa" ]] && [[ "${TOXENV#pypy}" == "$TOXENV" ]]; then
+    # Setup coverage tracking.
+    if [[ "$SKIP_COVERAGE" != "1" ]]; then
       PYTEST_DJANGO_COVERAGE=1
       export PYTEST_ADDOPTS='--cov=pytest_django --cov=tests --cov=pytest_django_test --cov-report=term-missing:skip-covered'
       export _PYTESTDJANGO_TOX_EXTRA_DEPS=pytest-cov

Makefile

@@ -17,11 +17,8 @@ $(VENV)/bin/pytest: $(VENV)/bin/python requirements.txt
 	$(VENV)/bin/pip install -Ur requirements.txt
 	touch $@
 
-$(VENV)/bin/sphinx-build: $(VENV)/bin/pip
-	$(VENV)/bin/pip install sphinx
-
-docs: $(VENV)/bin/sphinx-build
-	SPHINXBUILD=../$(VENV)/bin/sphinx-build $(MAKE) -C docs html
+docs:
+	tox -e docs
 
 # See setup.cfg for configuration.
 isort:

docs/changelog.rst

@@ -130,7 +130,7 @@ Compatibility
   database access was prevented on the cursor level. To be safer and prevent
   more cases, it is now prevented at the connection level. If you previously
   had tests which interacted with the databases without a database cursor, you
-  will need to mark them with the :func:`pytest.mark.django_db` marker or
+  will need to mark them with the ``pytest.mark.django_db`` marker or
   request the ``db`` fixture.
 
 * The previously undocumented internal fixtures ``_django_db_setup``,

docs/database.rst

@@ -246,7 +246,7 @@ django_db_blocker
 
 .. warning::
     It does not manage transactions and changes made to the database will not
-    be automatically restored. Using the :func:`pytest.mark.django_db` marker
+    be automatically restored. Using the ``pytest.mark.django_db`` marker
     or :fixture:`db` fixture, which wraps database changes in a transaction and
     restores the state is generally the thing you want in tests. This marker
     can be used when you are trying to influence the way the database is

docs/helpers.rst

@@ -207,7 +207,7 @@ is configured to be in the containing Django project.
 
 This fixture will ensure the Django database is set up.  Only
 required for fixtures that want to use the database themselves.  A
-test function should normally use the :py:func:`~pytest.mark.django_db`
+test function should normally use the ``pytest.mark.django_db``
 mark to signal it needs the database.
 
 ``transactional_db``
@@ -216,7 +216,7 @@ mark to signal it needs the database.
 This fixture can be used to request access to the database including
 transaction support.  This is only required for fixtures which need
 database access themselves.  A test function would normally use the
-:py:func:`~pytest.mark.django_db` mark to signal it needs the database.
+``pytest.mark.django_db`` mark to signal it needs the database.
 
 ``live_server``
 ~~~~~~~~~~~~~~~

docs/managing_python_path.rst

@@ -25,7 +25,7 @@ first file is found.
 
 If you have a custom project setup, have none or multiple ``manage.py`` files
 in your project, the automatic detection may not be correct. See
-:ref:`managing_the_python_path_explicilty` for more details on how to configure
+:ref:`managing_the_python_path_explicitly` for more details on how to configure
 your environment in that case.
 
 .. _managing_the_python_path_explicitly:

setup.py

@@ -31,6 +31,12 @@ def read(fname):
     python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*',
     setup_requires=['setuptools_scm>=1.11.1'],
     install_requires=['pytest>=3.6'],
+    extras_require={
+        'docs': [
+            'sphinx',
+            'Flask-Sphinx-Themes',
+        ]
+    },
     classifiers=['Development Status :: 5 - Production/Stable',
                  'Framework :: Django',
                  'Framework :: Django :: 1.8',

tox.ini

@@ -59,6 +59,11 @@ deps =
 commands =
     doc8 docs/
 
+[testenv:docs]
+deps =
+extras = docs
+commands = sphinx-build -W -b html -d docs/_build/doctrees docs docs/_build/html
+
 [testenv:readme]
 basepython = python3.5
 deps =