Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add option to emit separate files for <head> and <body> #14

Closed
gabor-varga opened this issue Apr 22, 2020 · 6 comments
Closed

Add option to emit separate files for <head> and <body> #14

gabor-varga opened this issue Apr 22, 2020 · 6 comments
Labels
enhancement New feature or request question Further information is requested

Comments

@gabor-varga
Copy link

Thanks for your support so far, I appreciate the effort.

I am working on including the generated HTML files in a documentation generated by sphinx (using reST).

The problem is, sphinx generates a wrapper HTML which already contains <head>. Since I include the generated HTML as-is, it causes problems since the document now has two heads. However, it is possible to handle adding additional items into this original <head> section with sphinx, and it would be easier if separate files were generated for the <head> and <body> sections of the output.

Adding this might be a feature bloat, or too specific use-case. What do you think? I can also implement a post-processing script that does the separation.
@dblanchette
Copy link
Collaborator

Hi @mrspacemankey,

We actually have the exact same use case. The problem for us was that beyond having two heads, the CSS from sphinx would clash with the one from bootstrap and from json-schema-for-humans.

Even though it is often seen as bad practice, we got the results we wanted with an iframe

.. raw:: html

    <iframe style="width: 100%; height: 80vh" frameBorder="0" src="./_static/schema_doc.html"></iframe>

That being said, I'm open to other ways of outputting the result!

@dblanchette dblanchette added enhancement New feature or request question Further information is requested labels Apr 22, 2020
@gabor-varga
Copy link
Author

Hi @dblanchette ,

I can confirm your case works, and even though I don't like iframes, it's a simple solution.

I still tried to solve the problem of the CSS clash of scripts. It is possible to modify the default sphinx template for the layout of pages as explained here. This way, the additional header can be added to sphinx.

However, this still causes an issue with CSS. I could solve it by manually re-ordering the items in <head> of the HTML output. The following line has to be placed after all the other includes from json-schema-for-humans. Then the CSS (at least for json-schema-for-humans) works. I still have to check if this does not break any CSS for the sphinx pages.

<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>

Of course, the problem is that the templating engine of sphinx does not allow for specifying the order of the header information, so I will stick with your solution for now, or just simply adding a direct link to the native HTML output of the json schema in the docs.

I will keep searching for a proper solution to adding the json schema in-line, as it would be very nice for documentation.

@gabor-varga
Copy link
Author

Looking at issue #4, it is connected to this. Replacing JS with CSS would fix this problem I think. It's probably a lot of work though.

@dblanchette
Copy link
Collaborator

Thanks for the additional information!

I just added a comment in #4 about having a version without JS (but also without the collapsible sections).

I'll close this one for now.

@GlenNicholls
Copy link

So I ran into this along with the other linked issue as I am also looking to include schema documentation in our Sphinx docs. Based on the previous note:

Even though it is often seen as bad practice, we got the results we wanted with an iframe

.. raw:: html

  <iframe style="width: 100%; height: 80vh" frameBorder="0" src="./_static/schema_doc.html"></iframe>

I noticed in #4 that there is now --config template_name=flat, is there a way to use that HTML/CSS to avoid iframe?

@e-lo
Copy link

e-lo commented Mar 13, 2023

I'd just like to add that I have a similar use case, but using mkdocs which I'm having to get around by writing a custom macro to edit the HTML output 👎 It would be great to have native plugins for both sphinx and mkdocs or easier access to the "content" as separate from the rendering.

@Hyrae Hyrae mentioned this issue Jun 18, 2024
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
enhancement New feature or request question Further information is requested
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
4 participants
@e-lo @dblanchette @gabor-varga @GlenNicholls