Merge pull request #872 from mpacer/fix_api_break

Fix api break

CONTRIBUTING.md

@@ -9,12 +9,33 @@ and the [IPython Contributing Guide](https://github.com/ipython/ipython/blob/mas
 In order to test all the features of nbconvert you need to have `pandoc` and
 `TexLive` installed. 
 
-In your environment `pip install nbconvert[all]` will be needed to be able to
+In your environment `pip install -e .[all]` will be needed to be able to
 run all of the tests and to test all of the features. 
 
-If you only want to run some of the tests run `pip install nbconvert[test]`.
+If you only want to run some of the tests run `pip install -e .[test]`.
+
+# Documentation
+
+NbConvert includes a substantial amount of both user and API documentation. 
+
+We use sphinx to build the API documentation. 
+
+Much of the user documentation is written in Jupyter Notebooks and converted on the fly with nbsphinx. 
+
+
+To build nbconvert's documentation you need to have `pandoc` and
+`TexLive` installed. 
+
+If you want to build the docs you will need to install the docs dependencies in addition to
+the standard dependencies. You can get all of the dependencies by running `pip install -e
+.[all]` and if you want only those needed to run the docs you can access them with `pip install -e .[docs]`.
 
 # Releasing
 
 If you are going to release a version of `nbconvert` you should also be capable
-of testing it. Please follow the instructions in [Testing](#testing).
+of testing it and building the docs. 
+
+Please follow the instructions in [Testing](#testing) and [Documentation](#documentation) if
+you are unfamiliar with how to do so.
+
+The rest of the release process can be found in [these release instructions](./docs/source/development_release.rst).

docs/README.md

@@ -17,9 +17,9 @@ is hosted on ReadTheDocs.
 
         $ source activate nbconvert_docs
 
-4. Create an editable install for nbconvert using
+4. Create an editable install for nbconvert with doc dependencies using
 
-        $ pip install -e ../. 
+        $ pip install -e ..[docs]
 
    or if you want, `cd ..` and `pip install . -e`. But then you will need to `cd docs` before
    continuing to the next step.

nbconvert/utils/pandoc.py

@@ -101,7 +101,7 @@ def check_pandoc_version():
                       "output of pandoc --version.\nContinuing...",
                       RuntimeWarning, stacklevel=2)
         return False
-    ok = check_version(v, _minimal_version, _maximal_version)
+    ok = check_version(v, _minimal_version, max_v=_maximal_version)
     if not ok:
         warnings.warn( "You are using an unsupported version of pandoc (%s).\n" % v +
                        "Your version must be at least (%s) " % _minimal_version +

nbconvert/utils/tests/test_version.py

@@ -0,0 +1,12 @@
+from ..version import check_version
+
+def test_check_version():
+    """Test the behaviour of check_versionself.
+    
+    This is mostly used to make sure the pandoc version is appropriate for the library.
+    """
+
+    assert check_version('1.19.2.4', '1.12.1')
+    assert check_version('2.2.3.2', '1.12.1')
+    assert check_version('1.19.2.4', '1.12.1', max_v='2.0')
+    assert not check_version('2.2.3.2', '1.12.1', max_v='2.0')

nbconvert/utils/version.py

@@ -11,7 +11,7 @@
 from distutils.version import LooseVersion
 
 
-def check_version(v, min_v, max_v):
+def check_version(v, min_v, max_v=None):
     """check version string v >= min_v and v < max_v
 
     Parameters
@@ -28,9 +28,9 @@ def check_version(v, min_v, max_v):
     is satisfied. Users on dev branches are responsible for keeping their own
     packages up to date.
     """
-
+    
     try:
-        return LooseVersion(v) >= LooseVersion(min_v) and LooseVersion(v) < LooseVersion(max_v)
+        below_max = LooseVersion(v) < LooseVersion(max_v) if max_v is not None else True
+        return LooseVersion(v) >= LooseVersion(min_v) and below_max
     except TypeError:
         return True
-

setup.py

@@ -200,12 +200,21 @@ def run(self):
     'testpath',
     'defusedxml',
 ]
+jupyter_client_req = 'jupyter_client>=4.2'
 
 extra_requirements = {
-    'test': ['pytest', 'pytest-cov', 'ipykernel', 'jupyter_client>=4.2'],
+    'test': ['pytest', 'pytest-cov', 'ipykernel', jupyter_client_req],
     'serve': ['tornado>=4.0'],
-    'execute': ['jupyter_client>=4.2'],
+    'execute': [jupyter_client_req],
+    'docs': ['sphinx>=1.5.1', 
+             'sphinx_rtd_theme',
+             'nbsphinx>=0.2.12', 
+             'sphinxcontrib_github_alt',
+             'ipython',
+             jupyter_client_req,
+             ],
 }
+
 extra_requirements['all'] = sum(extra_requirements.values(), [])
 setuptools_args['extras_require'] = extra_requirements