hazza/jupyterhub
1
0
Fork 0
mirror of https://github.com/jupyterhub/jupyterhub.git synced 2025-10-07 10:04:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

generate rest API with redoc

Browse Source 
via custom template
This commit is contained in:
Min RK
2024-02-07 12:30:57 +01:00
parent 2c93299764
commit 0082f5b3da
5 changed files with 67 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
.prettierignore
View File

@@ -1,3 +1,4 @@
share/jupyterhub/templates/
share/jupyterhub/static/js/admin-react.js
jupyterhub/singleuser/templates/
docs/source/_templates/

2
docs/source/_templates/page.html Normal file
View File

@@ -0,0 +1,2 @@
{%- set _meta = meta | default({}) %}
{%- extends _meta.page_template | default('!page.html') %}

34
docs/source/_templates/redoc.html Normal file
View File

@@ -0,0 +1,34 @@
{%- extends "!layout.html" %}
{# not sure why, but theme CSS prevents scrolling within redoc content
# If this were fixed, we could keep the navbar and footer
#}
{%- block css %}{%- endblock %}
{%- block docs_navbar %}{%- endblock %}
{%- block footer %}{% endblock %}
{%- block body_tag %}
<body>
{%- endblock %}
{%- block extrahead %}
{{ super() }}
<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700"
rel="stylesheet"
/>
<script src="{{ pathto('_static/redoc.js', 1) }}"></script>
{%- endblock %}
{%- block content %}
<redoc id="redoc-spec"></redoc>
<script>
if (location.protocol === "file:") {
document.body.innerText = "Rendered API specification doesn't work with file: protocol. Use sphinx-autobuild to do local builds of the docs, served over HTTP."
} else {
Redoc.init(
"{{ pathto('_static/rest-api.yml', 1) }}",
{{ meta.redoc_options | default({}) }},
document.getElementById("redoc-spec"),
);
}
</script>
{%- endblock %}

21
docs/source/conf.py
View File

@@ -7,13 +7,17 @@ import datetime
import io
import os
import subprocess
from pathlib import Path
from urllib.request import urlretrieve
from docutils import nodes
from sphinx.directives.other import SphinxDirective
from sphinx.util import logging
import jupyterhub
from jupyterhub.app import JupyterHub
logger = logging.getLogger(__name__)
# -- Project information -----------------------------------------------------
# ref: https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
#
@@ -119,7 +123,24 @@ class HelpAllDirective(SphinxDirective):
return [par]
templates_path = ["_templates"]
def stage_redoc_js(app, exception):
"""Download redoc.js to our static files"""
redoc_version = "2.1.3"
redoc_url = (
f"https://cdn.redoc.ly/redoc/v{redoc_version}/bundles/redoc.standalone.js"
)
dest = Path(app.builder.outdir) / "_static/redoc.js"
if not dest.exists():
logger.info(f"Downloading {redoc_url} -> {dest}")
urlretrieve(redoc_url, dest)
def setup(app):
app.connect("build-finished", stage_redoc_js)
app.add_css_file("custom.css")
app.add_directive("jupyterhub-generate-config", ConfigDirective)
app.add_directive("jupyterhub-help-all", HelpAllDirective)

37
docs/source/reference/rest-api.md
View File

@@ -1,33 +1,14 @@
<!---
This doc is part of the API references section of the References documentation.
--->
---
page_template: redoc.html
# see: https://redocly.com/docs/redoc/config/ for options
redoc_options:
hideHostname: true
hideLoading: true
---
(jupyterhub-rest-API)=
# JupyterHub REST API
Below is an interactive view of JupyterHub's OpenAPI specification.
<!-- client-rendered openapi UI copied from FastAPI -->
<link type="text/css" rel="stylesheet" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@3/swagger-ui.css">
<script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@4.1/swagger-ui-bundle.js"></script>
<!-- `SwaggerUIBundle` is now available on the page -->
<!-- render the ui here -->
<div id="openapi-ui"></div>
<script>
const ui = SwaggerUIBundle({
url: '../_static/rest-api.yml',
dom_id: '#openapi-ui',
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIBundle.SwaggerUIStandalonePreset
],
layout: "BaseLayout",
deepLinking: true,
showExtensions: true,
showCommonExtensions: true,
});
</script>
NOTE: The contents of this markdown file are not used,
this page is entirely generated from `_templates/redoc.html` and `_static/rest-api.yml`