I don't see how I can integrate the generated api.html</code

Another update on this: I am now just injecting a place holder <code class="notran

Integration with rest of documentation about redoc HOT 5 OPEN

sphinx-contrib commented on July 26, 2024 3

Integration with rest of documentation

from redoc.

Comments (5)

ikalnytskyi commented on July 26, 2024

Unfortunately, I do not know how to integrate it to Sphinx properly, i.e. so you can integrate it with a toctree. Sphinx uses docutils internally, and docutils is a freaking mess. :(

However, it's not true that you need to do absolute links. You can do relative (to docs/) links.

The point of this extension is to have Sphinx as the only tool you need to produce all-in-one docs, where you have your Sphinx documentation and ReDoc-rendered OpenAPI spec. I.e. perform ReDoc bundling and spec copying when you run Sphinx to build the docs.

from redoc.

rth commented on July 26, 2024

An imperfect solution is to link the ReDoc rendered spec to the main documentation with, the info->description field in the OpenAPI spec, e.g.

"info": {
        "description": "See <a href='./index.html'>main documentation</a> for more information about this project.",
        [...]
    }

and then in Sphinx create a new page that links to ReDoc rendered spec in the description.

Adding ReDoc rendered spec to sphinx's table of content (without passing by an intermediary page) would be ideal, and there is related discussion in sphinx-doc/sphinx#701 but with no clear solution as far as I can tell.

from redoc.

pohutukawa commented on July 26, 2024

What I'm just trying to do is to use the Sphinx raw:: html directive to include a file with the HTML fragments in it. It's a bit messy, but it sort of works when I pimp my build system to do the heavy lifting for me:

Strip the HTML boiler plate out of it (only keeping everything within the <body>...</body> tags in a file openapi.html
Raw include this file (above) with HTML content
Add some boiler plate of raw HTML resizing the width of the 3-panel-view to suit my needs.
I'm not a HTML/UI person, but with a bit of help this is what I've cobbled up and what I'm using (for now):

.. only:: html

   .. _specs-details:
   
   OpenAPI Specs Details
   =====================

   .. raw:: html
            
      <script>
        function resizeOpenapiElement() {
          var openapiElement = document.getElementById('openapiWidget');
          var parentElement = openapiElement.parentNode;
          parentElement.style.width = '150%';
        }
        document.body.addEventListener('load', resizeOpenapiElement, true);
      </script>
      <div id="openapiWidget">

   .. raw:: html
      :file: _static/openapi.html

   .. raw:: html
            
      </div>

I hope that helps already. And I'm happy as, if somebody has suggestions on how to handle this in a tidier way ... ;-)

from redoc.

pohutukawa commented on July 26, 2024

Another update on this:
I am now just injecting a place holder {{openapi_redoc}} between the opening/closing <div> tags in the message above. I'm extracting the content of the <body> only from the generated ReDoc HTML content, which I'm then injecting for the above place holder. This is all (Python) scripted to give easily working reproducible builds.
I have subtly altered the Sphinx Makefile to call my patch_openapi_redoc.py script to do all the steps of the job described above right after the Sphinx build.

from redoc.

sachin-suresh-rapyuta commented on July 26, 2024

I tried the above .. only:: html snippet and is there a way we can use the .yaml file instead of the path to the .html file?
I have placed the yaml file in custom directory (specs/openapi.yaml), I get the entire junk (unformatted) of yaml in the section "OpenAPI Specs Details".

from redoc.

Integration with rest of documentation about redoc HOT 5 OPEN

Comments (5)

Related Issues (20)

Recommend Projects

React

Vue.js

Typescript

TensorFlow

Django

Laravel

D3

Recommend Topics

javascript

web

server

Machine learning

Visualization

Game

Recommend Org

Facebook

Microsoft

Google

Alibaba

D3

Tencent