Add an intro to API reference; customize logo/title; add link to Get …

…Started in the navbar

docs/source/_static/js/insert-get-started.js

@@ -0,0 +1,12 @@
+document.addEventListener('DOMContentLoaded', function() {
+  var a = document.createElement("a");
+  a.textContent = "Get Started";
+  a.href = "https://rstudio.github.io/prism-experiments/guide/site/get-started.html";
+  a.style = "float:right; color:#5a5a5a; margin-right:5px; margin-top:5px; font-weight:600; text-decoration:none;";
+  a.setAttribute("data-toggle", "tooltip");
+  a.setAttribute("data-placement", "bottom");
+  a.setAttribute("data-original-title", "Learn Shiny for Python");
+
+  var nav = document.querySelector(".topbar-main");
+  nav.appendChild(a);
+}, false);

docs/source/_templates/layout.html

@@ -1,4 +1,5 @@
 
+<!-- Do not manually edit this file. It is automatically generated by the pyshinyapp extension -->
 {% extends "!layout.html" %}
 {% block extrahead %}
   <script type="module">

docs/source/conf.py

@@ -7,6 +7,8 @@
 import os
 import sys
 
+from sphinx.application import Sphinx
+
 # -- Path setup --------------------------------------------------------------
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -50,9 +52,18 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-#
+# https://sphinx-book-theme.readthedocs.io/en/latest/tutorials/get-started.html
 html_theme = "sphinx_book_theme"
 
+html_theme_options = {
+    "repository_url": "https://github.com/rstudio/prism",
+    "use_repository_button": True,
+}
+
+html_title = "for Python"
+
+html_logo = "images/shiny-logo.png"
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
@@ -68,3 +79,8 @@
 # don't! You'll get unhelpful pickling errors. https://github.com/sphinx-doc/sphinx/pull/6754
 # Instead, add them to the docs/source/sphinxext/ directory and add the name to the
 # extensions list above (as done for pyshinyapp).
+
+
+def setup(app: Sphinx) -> None:
+    # Add the 'Get Started' Link to the top navbar
+    app.add_js_file("js/insert-get-started.js")

docs/source/index.rst

@@ -1,7 +1,72 @@
-Shiny for Python API Reference
-==============================
+API Reference Intro
+===================
 
-* :ref:`search`
+This website documents the public API of Shiny (for Python). See the `Getting Started
+tutorial <https://rstudio.github.io/prism-experiments/guide/site/get-started.html>`_ for
+a more approachable introduction to the API. The left-hand sidebar lists the full public
+API, without any grouping, but the sections below (linked to the right-hand sidebar)
+break it into semantically similar groups. Most of the reference pages include a live
+example app at the bottom, or at least mention another page with a relevant example. See
+`here <https://rstudio.github.io/prism-experiments/>`_ for more on how to these basic
+apps are able to run purely in the browser (no server required) on a statically hosted
+site (more complex apps may require a server).
+
+We've intentionally designed Shiny's API so that you can ``from shiny import *`` to get
+access to most of what you need for most apps without introducing an excessive amount of
+namespace pollution. Namely, it gives you:
+
+* User interface (UI/HTML) helpers, available via the ``ui`` subpackage.
+
+  * To avoid clashing with this ``ui`` namespace when you do ``from shiny import *``, you'll want to name you UI object something else, like ``app_ui``.
+
+* Reactive programming utilities, available via the ``reactive`` subpackage.
+* Decorators for rendering ``output``, all of which start with ``render_*`` (e.g. ``@render_text()``, ``@render_plot()``, etc).
+
+  * We intentionally avoid a ``render`` subpackage so that 3rd party packages can define their own rendering functions without requring a different API.
+
+* A handful of other things you'll want for most apps (e.g., ``App``, ``Module``, etc).
+* If you're using type checking, you'll also want to use the ``Inputs``, ``Outputs``, and ``Session`` Classes
+  to type the instances supplied to your server function, for example:
+
+.. code-block:: python
+
+  from shiny import *
+
+  app_ui = ui.page_fluid(
+    ui.input_slider("n", "Value of n", min=1, max=10, value=5),
+    ui.output_text("n2")
+  )
+
+  def server(input: Inputs, output: Outputs, session: Session) -> None:
+      @output()
+      @render_text()
+      def n2():
+          return f"The value of n*2 is {input.n() * 2}"
+
+  app = App(app_ui, server)
+
+.. shinyapp::
+    :height: 200px
+
+    from shiny import *
+
+    app_ui = ui.page_fluid(
+      ui.input_slider("n", "Value of n", min=1, max=10, value=5),
+      ui.output_text("n2")
+    )
+
+    def server(input: Inputs, output: Outputs, session: Session) -> None:
+        @output()
+        @render_text()
+        def n2():
+            return f"The value of n*2 is {input.n() * 2}"
+
+    app = App(app_ui, server)
+
+
+
+API Reference
+=============
 
 .. currentmodule:: shiny
 

docs/sphinxext/pyshinyapp.py

@@ -44,6 +44,7 @@
 # and https://rstudio.github.io/prism-experiments/guide/site/components.html
 # for more/update details
 LAYOUT_TEMPLATE = f"""
+<!-- Do not manually edit this file. It is automatically generated by the pyshinyapp extension -->
 {{% extends "!layout.html" %}}
 {{% block extrahead %}}
   <script type="module">