Merge pull request #10 from ikalnytskyi/redoc-1.21.2

Redoc 1.21.2
sphinx-contrib · Mar 24, 2018 · 6b1865d · 6b1865d
2 parents e2cc892 + b93d136
commit 6b1865d
Show file tree

Hide file tree

Showing 7 changed files with 159 additions and 47 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,3 +1,16 @@
+1.4.0 (2018-03-24)
+``````````````````
+
+- Update ``redoc.js`` to ``1.21.2``. [:pr:`10`]
+
+- Add support for the following ReDoc options:
+
+  - ``hide-loading``
+  - ``native-scrollbars``
+  - ``untrusted-spec``
+
+  [:pr:`10`]
+
 1.3.0 (2017-05-12)
 ``````````````````
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -98,6 +98,16 @@ do is to:
     ``expand-responses`` (default: ``[]``)
       A list of response codes to be expanded by default.
 
+    ``hide-loading`` (default: ``False``)
+      Do not show loading animation. Useful for small OpenAPI specs.
+
+    ``native-scrollbars`` (default: ``False``)
+      Use native scrollbar for sidemenu instead of perfect-scroll. May
+      dramatically improve performance on big OpenAPI specs.
+
+    ``untrusted-spec`` (default: ``False``)
+      If set, the spec is considered untrusted and all HTML/markdown is
+      sanitized to prevent XSS.
 
 Demo
 ----
@@ -124,7 +134,7 @@ Changes
 Links
 -----
 
-* Documentation: https://sphinxcontrib-redoc.readthedocs.org/
+* Documentation: https://sphinxcontrib-redoc.readthedocs.io/
 * Source: https://github.com/ikalnytskyi/sphinxcontrib-redoc
 * Bugs: https://github.com/ikalnytskyi/sphinxcontrib-redoc/issues
 

diff --git a/sphinxcontrib/redoc.j2 b/sphinxcontrib/redoc.j2
@@ -16,7 +16,10 @@
            {{ 'required-props-first' if opts['required-props-first'] }}
            {{ 'no-auto-auth' if opts['no-auto-auth'] }}
            {{ 'path-in-middle-panel' if opts['path-in-middle-panel'] }}
-           {{ 'expand-responses="%s"' % ','.join(opts['expand-responses']) }}>
+           {{ 'hide-loading' if opts['hide-loading'] }}
+           {{ 'native-scrollbars' if opts['native-scrollbars'] }}
+           {{ 'untrusted-spec' if opts['untrusted-spec'] }}
+           {{ 'expand-responses="%s"' % ','.join(opts['expand-responses']) if opts['expand-responses'] }}>
     </redoc>
     <script src="{{ pathto('_static/redoc.js', 1) }}"></script>
   </body>

diff --git a/sphinxcontrib/redoc.js b/sphinxcontrib/redoc.js
diff --git a/sphinxcontrib/redoc.py b/sphinxcontrib/redoc.py
@@ -29,13 +29,6 @@ def render(app):
         # Setup options if they are not passed since 'redoc.j2' template
         # relies on them.
         ctx.setdefault('opts', {})
-        ctx['opts'].setdefault('lazy-rendering', False)
-        ctx['opts'].setdefault('suppress-warnings', False)
-        ctx['opts'].setdefault('hide-hostname', False)
-        ctx['opts'].setdefault('required-props-first', False)
-        ctx['opts'].setdefault('no-auto-auth', False)
-        ctx['opts'].setdefault('path-in-middle-panel', False)
-        ctx['opts'].setdefault('expand-responses', [])
 
         # The 'spec' may contain either HTTP(s) link or filesystem path. In
         # case of later we need to copy the spec into output directory, as

diff --git a/tests/test_integration.py b/tests/test_integration.py
@@ -1,61 +1,153 @@
 import os
-import re
+import textwrap
 
 import py
 import pytest
 import pkg_resources
+import jinja2
+import bs4
 
 from sphinx.application import Sphinx
 
 
 here = os.path.abspath(os.path.dirname(__file__))
 
 
-@pytest.fixture(scope='session')
-def sphinxdocs(tmpdir_factory):
-    srcdir = os.path.join(here, '..', 'docs')
-    outdir = tmpdir_factory.getbasetemp().strpath
-
-    Sphinx(
-        srcdir=srcdir,
-        confdir=srcdir,
-        outdir=outdir,
-        doctreedir=os.path.join(outdir, '.doctrees'),
-        buildername='html'
-    ).build()
-
-    yield py.path.local(srcdir), tmpdir_factory.getbasetemp()
-
-
-def test_redocjs_lib_is_copied(sphinxdocs):
-    srcdir, outdir = sphinxdocs
+@pytest.fixture(scope='function')
+def run_sphinx(tmpdir):
+    src = tmpdir.mkdir('src')
+    out = tmpdir.mkdir('out')
+
+    spec = py.path.local(here).join('..', 'docs', '_specs', 'github.yml')
+    spec.copy(src.mkdir('_specs').join('github.yml'))
+
+    def run(conf):
+        confpy = jinja2.Template(textwrap.dedent('''
+            import os
+
+            project = 'sphinxcontrib-redoc'
+            copyright = '2017, Ihor Kalnytskyi'
+
+            extensions = ['sphinxcontrib.redoc']
+            source_suffix = '.rst'
+            master_doc = 'index'
+            redoc = [
+                {
+                    'name': 'Github API (v3)',
+                    'page': 'api/github/index',
+                    'spec': '_specs/github.yml',
+                    {% if opts is not none %}
+                    'opts': {
+                        {% for key, value in opts.items() %}
+                        '{{ key }}': {{ value }},
+                        {% endfor %}
+                    },
+                    {% endif %}
+                },
+            ]
+        ''')).render(opts=conf)
+        src.join('conf.py').write_text(confpy, encoding='utf-8')
+        src.join('index.rst').ensure()
+
+        Sphinx(
+            srcdir=src.strpath,
+            confdir=src.strpath,
+            outdir=out.strpath,
+            doctreedir=out.join('.doctrees').strpath,
+            buildername='html'
+        ).build()
+
+    yield run
+
+
+def test_redocjs_lib_is_copied(run_sphinx, tmpdir):
+    outdir = tmpdir.join('out')
     extdir = py.path.local(
         pkg_resources.get_provider('sphinxcontrib.redoc').module_path)
 
+    run_sphinx({})
+
     assert outdir.join('_static', 'redoc.js').check()
     assert outdir.join('_static', 'redoc.js').computehash() \
         == extdir.join('redoc.js').computehash()
 
 
-def test_redocjs_page_is_generated(sphinxdocs):
-    srcdir, outdir = sphinxdocs
-
-    assert outdir.join('api', 'github', 'index.html').check()
+def test_openapi_spec_is_copied(run_sphinx, tmpdir):
+    srcdir, outdir = tmpdir.join('src'), tmpdir.join('out')
 
-    html = outdir.join('api', 'github', 'index.html').read()
-    patterns = [
-        r'<redoc spec-url="../../_specs/github.yml"\s+lazy-rendering\s+'
-        r'expand-responses="">\s*</redoc>',
-        r'<script src="../../_static/redoc.js">\s*</script>',
-    ]
-
-    for pattern in patterns:
-        assert re.search(pattern, html)
-
-
-def test_openapi_spec_is_copied(sphinxdocs):
-    srcdir, outdir = sphinxdocs
+    run_sphinx({})
 
     assert outdir.join('_specs', 'github.yml').check()
     assert outdir.join('_specs', 'github.yml').computehash() \
         == srcdir.join('_specs', 'github.yml').computehash()
+
+
+@pytest.mark.parametrize('options, attributes', [
+    (None,
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml')}),
+
+    ({},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml')}),
+
+    ({'lazy-rendering': False,
+      'suppress-warnings': False,
+      'hide-hostname': False,
+      'required-props-first': False,
+      'no-auto-auth': False,
+      'path-in-middle-panel': False,
+      'hide-loading': False,
+      'native-scrollbars': False,
+      'untrusted-spec': False,
+      'expand-responses': []},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml')}),
+
+    ({'lazy-rendering': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'lazy-rendering': ''}),
+
+    ({'suppress-warnings': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'suppress-warnings': ''}),
+
+    ({'hide-hostname': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'hide-hostname': ''}),
+
+    ({'required-props-first': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'required-props-first': ''}),
+
+    ({'no-auto-auth': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'no-auto-auth': ''}),
+
+    ({'path-in-middle-panel': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'path-in-middle-panel': ''}),
+
+    ({'hide-loading': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'hide-loading': ''}),
+
+    ({'native-scrollbars': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'native-scrollbars': ''}),
+
+    ({'untrusted-spec': True},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'untrusted-spec': ''}),
+
+    ({'expand-responses': ['200', '404']},
+     {'spec-url': os.path.join('..', '..', '_specs', 'github.yml'),
+      'expand-responses': '200,404'}),
+])
+def test_redocjs_page_is_generated(run_sphinx, tmpdir, options, attributes):
+    run_sphinx(options)
+
+    html = tmpdir.join('out').join('api', 'github', 'index.html').read()
+    soup = bs4.BeautifulSoup(html, 'html.parser')
+
+    assert soup.title.string == 'Github API (v3)'
+    assert soup.redoc.attrs == attributes
+    assert soup.script.attrs['src'] == os.path.join(
+        '..', '..', '_static', 'redoc.js')
diff --git a/tox.ini b/tox.ini
@@ -7,6 +7,7 @@ deps =
     sphinx_rtd_theme
     pytest
     flake8
+    beautifulsoup4
 commands =
     {envpython} setup.py check --strict
     {envpython} -m flake8 {posargs:.}