📚 DOCS: updating docs for rst (#18)

* updating docs for rst

* use docs

* black

Author: choldgraf

docs/conf.py

@@ -38,7 +38,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["jupyter_sphinx", "sphinx_thebe", "myst_parser"]
+extensions = ["jupyter_sphinx", "sphinx_thebe", "myst_parser", "sphinx_panels"]
 
 thebe_config = {
     "repository_url": "https://github.com/binder-examples/jupyter-stacks-datascience",
@@ -50,6 +50,8 @@
     # "codemirror-theme": "blackboard"  # Doesn't currently work
 }
 
+myst_admonition_enable = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -120,6 +122,7 @@
 # copybutton_image_path = "test/TEST_COPYBUTTON.png"
 # copybutton_selector = "div"
 
+panels_add_bootstrap_css = False
 
 # -- Options for HTMLHelp output ---------------------------------------------
 

docs/configure.md

@@ -35,6 +35,7 @@ code and Thebe will detect it.
 
 For example, the following code:
 
+``````{tabbed} MyST Markdown
 `````
 ````{container} thebe
 ```{code-block} r
@@ -46,6 +47,18 @@ print("hi")
 ```
 ````
 `````
+``````
+
+``````{tabbed} reStructuredText
+```{code-block} rst
+.. container:: thebe
+   .. code-block:: r
+      print("hi")
+
+   .. container:: output
+      "hi"
+```
+``````
 
 Defines a *parent container* in which we'll put both code and the output of the
 code. We'll use a `code-block` for the code, and another `container` node with our
@@ -132,12 +145,22 @@ qplot(hp, mpg, data=mtcars, shape=am, color=am,
 You can tag code blocks to run as soon as the kernel is ready (i.e., without any user input)
 by adding the `thebe-init` class to the code blocks. For example:
 
+`````{tabbed} MyST Markdown
 ````
 ```{code-block}
 :class: thebe, thebe-init
 print("hi")
 ```
 ````
+`````
+`````{tabbed} reStructuredText
+```rst
+.. code-block::
+   :class: thebe, thebe-init
+   
+   print("hi")
+```
+`````
 
 These code blocks will be run automatically once the kernel is ready, and their outputs
 will be displayed below.

docs/use.md

@@ -6,23 +6,15 @@ There are two steps to using `sphinx-thebe`. First, you must mark certain
 parts of your page as "ready for thebe". Next, you must insert a button onto
 the page to tell Thebe to initialize.
 
-```{tip}
-The examples on this page use a flavor of markdown called [MyST Markdown](https://myst-parser.readthedocs.io/en/latest/).
-However you can also use reStructuredText with `sphinx-thebe` in the same way. See
-[](examples/rst) for some tips.
-```
+:::{admonition,tip} Using reStructuredText vs. MyST Markdown
+The examples on this page use **MyST Markdown syntax**, a form of markdown that works with Sphinx directives. You can also use reStructuredText if you wish. For information about reStructuredText vs. MyST Markdown, see [the MyST Parser documentation](https://myst-parser.readthedocs.io/en/latest/using/syntax.html) as well as [](examples/rst) for some tips.
+:::
 
 ### Mark elements for thebe
 
 By default, thebe will be run on any elements in your documentation that contain
 the class `thebe` and that have a `<pre`> element underneath them.
 
-```{note}
-This documentation is written in [MyST Markdown](https://myst-parser.readthedocs.io),
-so the syntax for writing directives looks different from reStructuredText. However,
-rST works just fine as well.
-```
-
 You can add code blocks like so:
 
 ````
@@ -107,13 +99,15 @@ import matplotlib.pyplot as plt
 plt.scatter(*data, c=data[0], s=200)
 ```
 
-### Interactive outputs
+## Interactive outputs
 
-Interactive outputs are still a little bit flaky, but please try out
-`sphinx-thebe` with the interactive visualization library of your choice,
-and report back how things work!
+Interactive outputs work with `sphinx-thebe` **if their web dependencies are loaded**.
+
+Many interactive libraries assume that some javascript packages are pre-loaded in a notebook environment. For example, both Jupyter Lab and Notebook come bundled with `require.js`. To use visualization libraries that depend on this, **you must load these libraries on your own in Sphinx**. To do so, you can add the following to your `conf.py`:
+
+```python
+def setup(app):
+    app.add_js_file("url-of-package.js")
+```
 
-As a general rule, `sphinx-thebe` will only work with interactive libraries
-that are able to output self-contained bundles of HTML/JS that work on their own.
-Many Jupyter environments have libraries pre-loaded, and that will not be the case
-with `sphinx-thebe`.
+Note that some visualization libraries output *bundles of JavaScript/HTML* that will work out-of-the-box. You should consult the documentation of the library you wish to use in order to figure out how to configure it properly. See [the `thebe` examples](https://thebe.readthedocs.io/en/latest/) for examples of some popular visualization libraries.

setup.py

@@ -23,11 +23,18 @@
     url="https://github.com/executablebooks/sphinx-thebe",
     license="MIT License",
     packages=find_packages(),
-    package_data={"sphinx_thebe": ["_static/sphinx-thebe.css", "_static/sphinx-thebe.js",]},
+    package_data={
+        "sphinx_thebe": ["_static/sphinx-thebe.css", "_static/sphinx-thebe.js",]
+    },
     classifiers=["License :: OSI Approved :: MIT License"],
     install_requires=["sphinx>=1.8"],
     extras_require={
-        "sphinx": ["myst-parser[sphinx]", "sphinx-book-theme", "jupyter-sphinx"],
+        "sphinx": [
+            "myst-parser[sphinx]",
+            "sphinx-book-theme",
+            "jupyter-sphinx",
+            "sphinx-panels",
+        ],
         "testing": ["pytest", "pytest-regressions", "beautifulsoup4"],
     },
 )