Add an 'offline' option to embed the spec in the rendered page #14

etene · 2018-06-15T10:54:34Z

Hello,

First of all thanks for the work you've put in this project, it has been really useful to me.

However, I desperately needed to be able to generate a completely static HTML page that doesn't load the spec externally, and:

Redoc understandably doesn't support loading file:// URLs
starting a local http server would be waaay overkill
redoc-cli can do it, but requires a whole load of various Javascript libraries & isn't integrated into Sphinx

See: Redocly/redoc#149

I figured embedding the JSON spec in a <script> element would be the way to go. I haven't altered the default behavior, just added an offline parameter.

So what is does is, if the offline parameter is set to True, parse the JSON or YAML spec and embed it in the rendered page. Doesn't work for remote URLs, but I could fix that if you're interested.

Could you please consider merging ? Not yet though, I would like to update the docs first, if you're okay with it.

Thanks a lot !

ikalnytskyi · 2018-07-09T18:24:51Z

@etene I'm sorry that I was gone soooo long. Your PR makes sense to me, and I'd like accept this. However, I have a bunch of suggestion of what to improve. Would you like to work on them, so we can land it asap? or you would prefer if I simply continue your work?

etene · 2018-07-10T06:21:36Z

Hey, thanks for answering, no problem about the delay ! I agree there's room for improvement, so I'd be glad to hear about your suggestions and implement them.

…

ikalnytskyi

Sorry, I've been away for couple days. I left some comments here, could you please take a look?

ikalnytskyi · 2018-07-10T06:38:40Z

sphinxcontrib/redoc.py

-            ctx['spec'] = os.path.join('_specs', specname)
+        # "Offline" mode: the JSON spec is embedded in the page
+        # TODO: only works for local files: add remote files download ?
+        if ctx.get('offline') is True:


I don't like offline word in this context, perhaps we can choose a better word. What do you think about embed or single-page or embed_spec?

embed sounds better to me, I'll change it

ikalnytskyi · 2018-07-12T17:18:58Z

sphinxcontrib/redoc.py

+            # Parse & dump the spec to have it as properly formatted json
+            with io.open(os.path.join(app.confdir, ctx['spec'])) as specfp:
+                # Dumb heuristic
+                parser_module = json if ctx['spec'].endswith("json") else yaml


YAML could be used to parse JSON. For the sake of simplicity, I'd go with YAML loading.

P.S: I mean, json is usually much faster than YAML in parsing, but this is not performance critical part. I mean end users wouldn't even notice that.

I didn't even know this was possible. Simpler, OK with me.

ikalnytskyi · 2018-07-12T17:26:49Z

sphinxcontrib/redoc.j2

+    </script>
+    <script>
+        var spec = JSON.parse(document.getElementById("spec").innerHTML)
+        Redoc.init(spec);


I think since we have this init function here anyway, there's no much sense in passing redoc options via HTML attributes. Let's pass them via JavaScript instead. So on top level you will have only empty <redoc></redoc> tag.

I'm not a web developer so not really familiar with all that Javascript & HTML, but it seems from the docs that if we pass options to the init function, they must be in camelCase.
However sphinxcontrib-redoc's options are in "kebab-case" . I can't pass them directly this way.

Here's what I can do:

Change sphinxcontrib-redoc's configuration options to camelCase (breaking change :-/ )

Convert options from one form to the other (invisible for users but weird for future code readers)

What would you prefer ? Have I understood what you wanted correctly ?

Yes, you understand it right. I was thinking about making uni-drectional map of kebab notation to camelCase. However, now I think it could be done in separate PR, so don't bother yourself. I think moving "spec" passing (either JSON or URL) to one place (ReDoc.init) is good enough for this PR. Thanks!

Great ! Just leave me some time to update the docs regarding this PR's feature, unless you want to do it, and I think it will be mergeable.

ikalnytskyi · 2018-07-12T17:27:55Z

sphinxcontrib/redoc.py

+                                     % (ctx['spec'], ver))
+
+                ctx['spec'] = json.dumps(spec_contents)
+        else:


I think it makes sense to join this else and if below to reduce indentation level, like this:

# 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 # otherwise it won't be available when the result is deployed. elif not ctx['spec'].startswith(('http', 'https')):

…f the code

ikalnytskyi

@etene thanks for working on this! I left couple stylistic comments. I believe we are really close to merge this, I'll wait for changes in docs. Once they are done, I'll gladly merge this.

ikalnytskyi · 2018-07-18T11:28:02Z

sphinxcontrib/redoc.py

@@ -30,10 +32,24 @@ def render(app):
        # relies on them.
        ctx.setdefault('opts', {})

+        # "Embed" mode: the JSON spec is embedded in the page


Can we change a comment into something like this? I think it might be helpful for readers to understand a rationale behind this chunk of code.

# In embed mode, we are going to embed the whole OpenAPI spec into # produced HTML. The rationale is very simple: we want to produce # browsable HTMLs ready to be used without any web server.

yes, yours is better, i'll change it

ikalnytskyi · 2018-07-18T11:28:51Z

sphinxcontrib/redoc.py

@@ -30,10 +32,24 @@ def render(app):
        # relies on them.
        ctx.setdefault('opts', {})

+        # "Embed" mode: the JSON spec is embedded in the page
+        # TODO: only works for local files: add remote files download ?


Personal opinion: no TODOs in code, they will never be fixed. :) If you think it's important to implement, could you please create a followup issue instead?

I agree, I'll open an issue (and maybe do it if I have some time)

ikalnytskyi · 2018-07-18T11:34:44Z

sphinxcontrib/redoc.py

+        # TODO: only works for local files: add remote files download ?
+        if ctx.get('embed') is True:
+            # Parse & dump the spec to have it as properly formatted json
+            with io.open(os.path.join(app.confdir, ctx['spec'])) as specfp:


Hm, I believe we should explicitly set an encoding. If I'm not mistaken by default will be used encoding extracted from current locale, but OpenAPI spec may use another encoding.

So I can think about two options:

Explicitly use UTF-8 and say that only UTF-8 specs are supported. At least we will know for sure which encoding to use to deal with files no matter which system we're running on.

Use encoding from Sphinx config: env.config.source_encoding, and say that the specs must have the same encoding as other Sphinx documents.

Read encoding value from per-spec configuration.

While third item is more flexible, it would require additional changes and thorough thinking. I'd suggest to go with either (1) or (2) in this PR.

I'll implement (1) for now. Since the spec is generated by something that has nothing to do with Sphinx, I'd be reluctant to tie them together.

ikalnytskyi · 2018-07-18T11:35:25Z

tests/test_integration.py

-            ]
-        ''')).render(opts=conf)
+            redoc = {{ redoc }}
+        ''')).render(redoc=pprint.pformat([defaultconf]))


Sorry, I maybe missed that, but what's the point in having pprint.pformat here?

Good catch, it's probably something left over from testing, when I wanted the rendered template to be more human-readable. I'll remove it.

- use explicit encoding when opening specs (to be documented) - improve the comment for the embed option - remove useless debug pprint in tests

etene · 2018-07-19T07:54:45Z

I think this should be about it, tell me if you have any more comments !

ikalnytskyi · 2018-07-28T06:40:01Z

@etene Looks good! Thank you very much!

add an 'offline' option to embed the spec in the rendered page

3c3d33c

ikalnytskyi reviewed Jul 12, 2018

View reviewed changes

changed the option name from 'offline' to 'embed', simplified parts o…

75bd133

…f the code

ikalnytskyi reviewed Jul 18, 2018

View reviewed changes

PR review fixes

d17abaa

- use explicit encoding when opening specs (to be documented) - improve the comment for the embed option - remove useless debug pprint in tests

etene force-pushed the offline-spec branch from c7b2bd5 to 94ea1cc Compare July 19, 2018 07:49

Mention the embed option in the docs

2f54b32

etene force-pushed the offline-spec branch from 94ea1cc to 2f54b32 Compare July 19, 2018 07:50

etene changed the title ~~WIP: add an 'offline' option to embed the spec in the rendered page~~ Add an 'offline' option to embed the spec in the rendered page Jul 19, 2018

fix regression in template

4152f2a

etene force-pushed the offline-spec branch from 62bba03 to 4152f2a Compare July 26, 2018 10:23

ikalnytskyi merged commit cda6a47 into sphinx-contrib:master Jul 28, 2018

lalib mentioned this pull request Jul 31, 2018

Unable to resolve $ref pointer "file:///openapi.json" Redocly/redoc#587

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add an 'offline' option to embed the spec in the rendered page #14

Add an 'offline' option to embed the spec in the rendered page #14

etene commented Jun 15, 2018

ikalnytskyi commented Jul 9, 2018

etene commented Jul 10, 2018 via email

ikalnytskyi left a comment

ikalnytskyi Jul 10, 2018

etene Jul 13, 2018

ikalnytskyi Jul 12, 2018

etene Jul 13, 2018

ikalnytskyi Jul 12, 2018

etene Jul 13, 2018

etene Jul 13, 2018

ikalnytskyi Jul 17, 2018

etene Jul 18, 2018

ikalnytskyi Jul 12, 2018

etene Jul 13, 2018

ikalnytskyi left a comment

ikalnytskyi Jul 18, 2018

etene Jul 19, 2018

ikalnytskyi Jul 18, 2018

etene Jul 19, 2018

ikalnytskyi Jul 18, 2018

etene Jul 19, 2018

ikalnytskyi Jul 18, 2018

etene Jul 19, 2018

etene commented Jul 19, 2018

ikalnytskyi commented Jul 28, 2018

Add an 'offline' option to embed the spec in the rendered page #14

Add an 'offline' option to embed the spec in the rendered page #14

Conversation

etene commented Jun 15, 2018

ikalnytskyi commented Jul 9, 2018

etene commented Jul 10, 2018 via email

ikalnytskyi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ikalnytskyi left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

etene commented Jul 19, 2018

ikalnytskyi commented Jul 28, 2018