DOCS: Improve documentation

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 = ["sphinx_togglebutton"]
+extensions = ["myst_nb", "sphinx_design", "sphinx_togglebutton"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -78,13 +78,15 @@
 # html_theme = "alabaster"
 
 html_theme_options = {
-    "single_page": True,
     "repository_url": "https://github.com/executablebooks/sphinx-togglebutton",
     "use_repository_button": True,
     "use_issues_button": True,
     "use_edit_page_button": True,
+    "home_page_in_toc": True,
 }
 
+myst_enable_extensions = ["colon_fence"]
+
 # 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".

docs/index.md

@@ -0,0 +1,67 @@
+# `sphinx-togglebutton`
+
+A small sphinx extension to add "toggle button" elements to sections of your page.
+This allows you to:
+
+- Collapse admonitions (notes, warnings, etc) so that their content is hidden
+  until users click a toggle button. See {ref}`dropdown-admonitions`.
+- Collapse arbitrary chunks of content on your page with a `toggle` directive.
+  See {ref}`toggle-directive`.
+
+:::{admonition} For example, click the "+" button to the right:
+:class: dropdown
+
+Here's a toggled note! You can put all kinds of stuff in here!
+:::
+
+You can also add a toggle button to arbitrary chunks of content.
+For example, click the toggle button to the right just below.
+
+::::{toggle}
+:::{admonition} Wow!
+:class: tip
+
+It's a code block!
+
+```python
+a = "wow, very python"
+```
+:::
+::::
+
+See {ref}`usage` for more information.
+
+:::{admonition} Check out sphinx-panels as well!
+:class: tip
+
+For a bootstrap-based "dropdown" directive that uses pure CSS, check out
+[Sphinx Panels](https://sphinx-panels.readthedocs.io/en/latest/#dropdown-usage)
+:::
+
+```{toctree}
+use
+reference
+```
+
+## Installation
+
+You can install `sphinx-togglebutton` with `pip`:
+
+```bash
+pip install sphinx-togglebutton
+```
+
+Then, activate it in your `sphinx` build by adding it to your `conf.py` configuration
+file, like so:
+
+E.g.:
+
+```python
+extensions = [
+    ...
+    'sphinx_togglebutton'
+    ...
+]
+```
+
+See {ref}`usage` for information about how to use `sphinx-togglebutton`.