docs: build fixes

Signed-off-by: Sorin Sbarnea <sorin.sbarnea@gmail.com>

.gitignore

@@ -30,3 +30,4 @@ tests/test-reports-*/*
 /ChangeLog
 /AUTHORS
 /tests/build
+/.pytest_cache

Makefile

@@ -26,6 +26,9 @@ package:
 req:
 	@$(PREFIX)requires.io update-site -t ac3bbcca32ae03237a6aae2b02eb9411045489bb -r $(PACKAGE_NAME)
 
+hooks:
+	@$(PREFIX)python -m flake8 --install-hook 2>/dev/null || true
+
 install: prepare
 	$(PREFIX)pip install .
 
@@ -54,7 +57,6 @@ testspace:
 lint:
 	@echo "INFO:	linting...."
 	$(PREFIX)python -m flake8
-	@$(PREFIX)python -m flake8 --install-hook 2>/dev/null || true
 
 test: prepare lint
 	@echo "INFO:	test"

docs/Makefile

@@ -2,10 +2,11 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = build
+SOURCE_DATE_EPOCH = $(shell git log -1 --format=%ct)
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4

docs/conf.py

@@ -24,7 +24,7 @@
 # -- General configuration -----------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
-# needs_sphinx = '1.0'
+needs_sphinx = '1.6.5'
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
@@ -73,7 +73,7 @@
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
-# today = ''
+today = "1"
 # Else, today_fmt is used as the format for a strftime call.
 # today_fmt = '%B %d, %Y'
 
@@ -140,7 +140,7 @@
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -166,10 +166,10 @@
 html_show_sourcelink = True
 
 # If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
-html_show_sphinx = True
+html_show_sphinx = False
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-html_show_copyright = True
+html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the

docs/contributing.rst

@@ -72,24 +72,25 @@ Issues and Feature Requests
   * If possible, create a pull request with a (failing) test case demonstrating
     what's wrong. This makes the process for fixing bugs quicker & gets issues
     resolved sooner.
-  * Here is an template::
+  * Here is an template
+    ::
 
-    Description: <SUMMARIZE ISSUE>
+        Description: <SUMMARIZE ISSUE>
 
-    Python Intepreter: <VERSION>
-    jira-python: <VERSION>
-    OS: <OPERATING SYSTEM>
-    IPython (Optional): <VERSION>
-    Other Dependencies:
+        Python Intepreter: <VERSION>
+        jira-python: <VERSION>
+        OS: <OPERATING SYSTEM>
+        IPython (Optional): <VERSION>
+        Other Dependencies:
 
-    Steps To Reproduce:
-        1. <STEP>
-        2. <STEP>
-        3. <STEP>
-        ...
+        Steps To Reproduce:
+            1. <STEP>
+            2. <STEP>
+            3. <STEP>
+            ...
 
-    Stack Trace:
-        <TRACE>
+        Stack Trace:
+            <TRACE>
 
 
 Issues

docs/examples.rst

@@ -218,6 +218,7 @@ Searching
 
 Leverage the power of `JQL <https://confluence.atlassian.com/display/JIRA/Advanced+Searching>`_
 to quickly find the issues you want::
+
     # Search returns first 50 results, `maxResults` must be set to exceed this
     issues_in_proj = jira.search_issues('project=PROJ')
     all_proj_issues_but_mine = jira.search_issues('project=PROJ and assignee != currentUser()')

docs/requirements-rtd.txt

@@ -0,0 +1,3 @@
+pbr>=3.0.0
+sphinx>=1.7.1
+sphinx_rtd_theme

requirements-dev.txt

@@ -0,0 +1,21 @@
+# this file is needed by readthedocs.org so don't move them in another place
+coveralls>=1.1
+docutils>=0.12
+flaky
+hacking>=0.13
+MarkupSafe>=0.23
+oauthlib
+py >= 1.4
+pytest-cache
+pytest-cov
+pytest-instafail
+pytest-xdist>=1.14
+pytest>=2.9.1
+requires.io
+tenacity
+tox-pyenv
+tox>=2.3.1
+unittest2; python_version<'3.1'
+wheel>=0.24.0
+xmlrunner>=1.7.7
+yanc>=0.3.3

setup.cfg

@@ -7,9 +7,9 @@ maintainer-email = sorin.sbarnea@gmail.com
 summary = Python library for interacting with JIRA via REST APIs.
 description-file = 
     README.rst
-    ChangeLog
-# Do not include ChangeLog in description-file because its Unicode chars 
-# will break setup.cfg. See https://github.com/pycontribs/jira/issues/512
+# Do not include ChangeLog in description-file due to multiple reasons:
+# - Unicode chars, see https://github.com/pycontribs/jira/issues/512
+# - Breaks ability to perform `python setup.py install`
 
 home-page = https://github.com/pycontribs/jira
 license = BSD
@@ -49,29 +49,6 @@ opt =
     PyJWT
     requests_jwt
     requests_kerberos
-testing =
-    coveralls>=1.1
-    docutils>=0.12
-    flaky
-    hacking>=0.13
-    MarkupSafe>=0.23
-    oauthlib
-    py >= 1.4
-    pytest-cache
-    pytest-cov
-    pytest-instafail
-    pytest-xdist>=1.14
-    pytest>=2.9.1
-    requires.io
-    sphinx>=1.3.5
-    sphinx_rtd_theme
-    tenacity
-    tox-pyenv
-    tox>=2.3.1
-    unittest2:python_version<'3.1'
-    wheel>=0.24.0
-    xmlrunner>=1.7.7
-    yanc>=0.3.3
 
 [entry_points]
 console_scripts =

setup.py

@@ -1,5 +1,4 @@
 #!/usr/bin/env python
-
 import setuptools
 
 # In python < 2.7.4, a lazy loading of package `pbr` will break
@@ -12,5 +11,5 @@
 
 
 setuptools.setup(
-    setup_requires=['pbr>=3.0.0', 'setuptools>=17.1', 'pytest-runner'],
+    setup_requires=['pbr>=3.0.0', 'setuptools>=17.1', 'pytest-runner', 'sphinx>=1.6.5'],
     pbr=True)

tox.ini

@@ -6,16 +6,20 @@ skip_missing_interpreters = true
 [testenv:docs]
 basepython=python
 changedir=docs
+deps =
+    -rrequirements.txt
+    -rdocs/requirements-rtd.txt
 commands=
-    sphinx-build -W -b html -d {envtmpdir}/doctrees .  {envtmpdir}/html
+    bash -c 'cd {toxinidir}/docs && make html'
 
 [testenv]
 usedevelop = True
-deps = -rrequirements.txt
+deps =
+    -rrequirements.txt
+    -rrequirements-dev.txt
 extras =
     cli
     opt
-    testing
 sitepackages=False
 platform =
        win: windows
@@ -28,6 +32,11 @@ commands=
 passenv =
     CI_JIRA_*
     TRAVIS*
+    XDG_CACHE_HOME
+envars =
+    PIP_DISABLE_PIP_VERSON_CHECK=1
+whitelist_externals =
+    bash
 
 [travis:after]
 toxenv = py27