Add redoc directive

.editorconfig

@@ -0,0 +1,10 @@
+[*]
+charset = utf-8
+indent_size = 2
+indent_style = space
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.py]
+indent_size = 4
+max_line_length = 79

docs/conf.py

@@ -13,8 +13,8 @@
 exclude_patterns = ['_build']
 pygments_style = 'sphinx'
 extlinks = {
-    'issue': ('https://github.com/ikalnytskyi/sphinxcontrib-redoc/issues/%s', '#'),
-    'pr': ('https://github.com/ikalnytskyi/sphinxcontrib-redoc/pull/%s', 'PR #'),
+    'issue': ('https://github.com/ikalnytskyi/sphinxcontrib-redoc/issues/%s', '#%s'),
+    'pr': ('https://github.com/ikalnytskyi/sphinxcontrib-redoc/pull/%s', 'PR #%s'),
 }
 redoc = [
     {

docs/index.rst

@@ -23,6 +23,13 @@ small first step:
 Usage
 -----
 
+.. note::
+
+  For info about ``redoc`` directive, please visit a :ref:`redoc_directive_doc`.
+
+  .. versionadded:: 1.7.0
+
+
 The whole configuration is done via Sphinx's ``conf.py``. All you have to
 do is to:
 
@@ -168,3 +175,8 @@ Links
 .. _ReDoc: https://github.com/Rebilly/ReDoc
 .. _the proof: api/github/
 .. _sphinxcontrib-openapi: https://sphinxcontrib-openapi.readthedocs.io/
+
+.. toctree::
+  :hidden:
+
+  redoc_directive

docs/redoc_directive.rst

@@ -0,0 +1,116 @@
+.. _redoc_directive_doc:
+
+ReDoc Directive
+===============
+
+.. versionadded:: 1.7.0
+
+API
+---
+
+.. rst:directive:: redoc
+
+   .. rst:directive:option:: name: <name>
+
+      An API (human readable) name that will be used as page title.
+
+   .. rst:directive:option:: spec: <spec_path>
+
+      A path to the OpenAPI spec file. The path is relative to the
+      document where the directive is used.
+
+   .. rst:directive:option:: embed
+
+      *Disabled by default*
+
+      If set, the ``spec`` will be embedded into the rendered HTML page.
+      Useful for cases when a browsable API ready to be used without any web
+      server is needed.
+      The ``spec`` must be an ``UTF-8`` encoded JSON on YAML OpenAPI spec;
+      embedding an external ``spec`` is currently not supported.
+
+  .. rst:directive:option:: template: <template_path>
+
+    Path to non-default template to use to render ReDoc HTML page. Must be either
+    passed, or omitted. You can also write template in directive body. 
+
+    .. warning::
+
+        When custom template is used, settings such as ``name``, ``embed`` or
+        ``opts`` may not work if they are not supported by the template. Use
+        custom templates with caution.
+
+  .. rst:directive:option:: opt.lazy-rendering
+
+    *Disabled by default*
+
+    If set, enables lazy rendering mode which is useful for APIs with big
+    number of operations (e.g. > 50). In this mode ReDoc shows initial
+    screen ASAP and then renders the rest operations asynchronously while
+    showing progress bar on the top.
+
+  .. rst:directive:option:: opt.suppress-warnings
+
+    *Disabled by default*
+
+    If set, no warnings are rendered at the top of the document.
+
+  .. rst:directive:option:: opt.hide-hostname
+
+    *Disabled by default*
+
+    If set, both protocol ans hostname are not shown in the operational
+    definition.
+
+  .. rst:directive:option:: opt.required-props-firs
+
+    *Disabled by default*
+
+    If set, ReDoc shows required properties first in the same order as in
+    ``required`` array. Please note, it may be slow.
+
+  .. rst:directive:option:: opt.expand-responses
+
+    *Empty by default*
+
+    A list of response codes to be expanded by default, separated by comma ``,``.
+
+    Example: ``:opt.expand-responses: 200, 201, 204``
+
+  .. rst:directive:option:: opt.hide-loading
+
+    *Disabled by default*
+
+    Do not show loading animation. Useful for small OpenAPI specs.
+
+  .. rst:directive:option:: opt.native-scrollbars
+
+    *Disabled by default*
+
+    Use native scrollbar for sidemenu instead of perfect-scroll. May
+    dramatically improve performance on big OpenAPI specs.
+
+  .. rst:directive:option:: opt.untrusted-spec
+
+    *Disabled by default*
+
+    If set, the spec is considered untrusted and all HTML/markdown is
+    sanitized to prevent XSS.
+
+
+
+Example
+-------
+
+.. code:: rst
+
+    .. redoc::
+       :name: GitHub API
+       :spec: _specs/github.yml
+       :opt.lazy-rendering: true
+
+.. redoc::
+   :name: GitHub API
+   :spec: _specs/github.yml
+   :opt.lazy-rendering:
+   :opt.hide-hostname:

setup.py

@@ -47,6 +47,9 @@
         'Programming Language :: Python :: 3.6',
         'Programming Language :: Python :: 3.7',
         'Programming Language :: Python :: 3.8',
+        'Programming Language :: Python :: 3.9',
+        'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
     ],
     namespace_packages=['sphinxcontrib'],
 )

sphinxcontrib/redoc.j2

@@ -9,32 +9,33 @@
     </style>
   </head>
   <body>
-    <redoc
-           {{ 'lazy-rendering' if opts['lazy-rendering'] }}
-           {{ 'suppress-warnings' if opts['suppress-warnings'] }}
-           {{ 'hide-hostname' if opts['hide-hostname'] }}
-           {{ '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'] }}
-           {{ '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 id="{{ page }}"
+        {{ 'lazy-rendering' if opts['lazy-rendering'] -}}
+        {{ 'suppress-warnings' if opts['suppress-warnings'] -}}
+        {{ 'hide-hostname' if opts['hide-hostname'] -}}
+        {{ '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'] -}}
+        {{ '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>
     {% if embed %}
     <script type="application/json" id="spec">
-    {{ spec }}
+        {{ spec }}
     </script>
     {% endif %}
     <script>
-        {% if embed %}
+        {% if embed -%}
         var spec = JSON.parse(document.getElementById("spec").innerHTML);
-        {% else %}
+        {%- else -%}
         var spec = "{{ pathto(spec, 1) }}";
-        {% endif %}
-        Redoc.init(spec);
+        {%- endif %}
+        Redoc.init(spec, {}, document.getElementById("{{ page }}"));
     </script>
+
   </body>
 </html>