Integration with rest of documentation

Archelyst commented 6 years ago

I don't see how I can integrate the generated api.html into my documentation. It's just there in the documentation folder and I cannot even link to it unless I use absolute links, right? So what does this extension actually do related to Sphinx? It would be great if I could link to it from a toctree.

ikalnytskyi commented 6 years ago

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.

rth commented 5 years ago

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 https://github.com/sphinx-doc/sphinx/issues/701 but with no clear solution as far as I can tell.

pohutukawa commented 5 years ago

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 ... ;-)

pohutukawa commented 5 years ago

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.

sachin-suresh-rapyuta commented 2 years ago

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".

sphinx-contrib / redoc

Integration with rest of documentation #15