add ToC docs

disberd · Aug 31, 2023 · 8da2d36 · 8da2d36
1 parent 5ccfd16
commit 8da2d36
Show file tree

Hide file tree

Showing 4 changed files with 60 additions and 1 deletion.
diff --git a/docs/make.jl b/docs/make.jl
@@ -17,6 +17,7 @@ makedocs(;
         "index.md",
         "basic_widgets.md",
         "latex_equations.md",
+        "toc.md",
     ],
 )
 

diff --git a/docs/src/structbond.md b/docs/src/structbond.md
@@ -0,0 +1,6 @@
+# StructBond Module
+
+The StructBondModule submodule of PlutoExtras defines and exports functionality to easily create widgets for custom structure and combine multiple bonds together in a convenient floating side table.
+
+!!! note
+    The StructBondModule is currently not re-exported by PlutoExtras so it has to be explicitly used with `using PlutoExtras.StructBondModule`
diff --git a/docs/src/toc.md b/docs/src/toc.md
@@ -0,0 +1,48 @@
+# Extended ToC
+PlutoExtras defines and export an extension of the TableOfContents from PlutoUI. This alternative ToC just wraps the one from PlutoUI and adds functionality to it.
+It can be called by having a cell that contains the exported function [`ExtendedTableOfContents`](@ref)
+
+## Functionalities
+This extended ToC provides the following functionalities:
+- Hiding Heading/Cells both from ToC and from the notebook visualization
+- Collapsing Headings within the ToC
+- Saving the hidden/collapsed status of ToC entries on the notebook file, for persistent state across notebook reload.
+- Moving groups of cells (below a common heading) around conveniently from the ToC
+
+### Hiding Heading/Cells
+Hiding headings and all connected cells from notebook view can be done via ExtendedTableOfContents
+- All cells before the first heading are automatically hidden from the notebook
+- All hidden cells/headings can be shown by pressing the _eye_ button that appears while hovering on the ToC title. 
+  - When the hidden cells are being shown, the hidden headings in the ToC are underlined
+- Hidden status of specific headings in the notebook can be toggled by pressing on the eye button that appears to the left each heading when hovering over them
+
+### Collapsing Headings in ToC
+ToC headings are grouped based on heading level, sub-headings at various levels can be collapsed by using the caret symbol that appears to the left of headings in the ToC upon hover.
+
+### Save Hide/Collapsed status on notebook file
+Preserving the status of collapsed/hidden heading is supported by writing to the notebook file using notebook and cell metadata, allowing to maintain the status even upon reload of Julia/Pluto
+- When the current collapsed/hidden status of each heading is not reflected in the notebook file, a save icon/button appears on the left of the ToC title upon hover. Clicking the icon saves the current state in the notebook file.
+
+### Changing Headings/Cells order
+The `ExtendedTableOfContents` allow to re-order the cell groups identified by each heading within the notebook:
+- Each cell group is identified by the cell containing the heading, plus all the cells below it and up to the next heading (excluded)
+- Holding the mouse on a ToC heading triggers the ability to move headings around
+  - The target heading is surrounded by a dashed border
+  - While moving the mouse within the ToC, a visual separator appears to indicate the position where the dragged heading will be moved to, depending on the mouse position
+  - Hovering on collapsed headings for at least 300ms opens them up to allow moving headings within collapsed parents
+- By default, headings can only be moved below or above headings of equal or lower level (H1 < H2 < H3...)
+  - Holding shift during the dragging process allows to put headings before/after any other heading regardless of the level
+
+## Examples
+### State Manipulation
+![State_Manipulation](https://user-images.githubusercontent.com/12846528/217245898-5166682d-b41d-4f1e-b71b-4d7f69c8f192.gif)
+
+### Cell Reordering
+
+![Cell_Reordering](https://user-images.githubusercontent.com/12846528/217245256-58e4d537-9547-42ec-b1d8-2994b6bcaf51.gif)
+
+## API
+```@docs
+ExtendedTableOfContents
+show_output_when_hidden
+```
diff --git a/test/notebooks/extended_toc.jl b/test/notebooks/extended_toc.jl
@@ -38,10 +38,13 @@ md"""
 ## Hidden Heading
 """
 
+# ╔═╡ 77e467b9-c86c-4f13-a259-c38dfd80a3aa
+2 # This will be completely hidden
+
 # ╔═╡ f6e74270-bd75-4367-a0b2-1e10e1336b6c
 # ╠═╡ skip_as_script = true
 #=╠═╡
-3 |> show_output_when_hidden
+3 |> show_output_when_hidden # This will keep showing
   ╠═╡ =#
 
 # ╔═╡ 091dbcb6-c5f6-469b-889a-e4b23197d2ad
@@ -446,6 +449,7 @@ version = "17.4.0+2"
 # ╟─48540378-5b63-4c20-986b-75c08ceb24b7
 # ╟─7dce5ffb-48ad-4ef4-9e13-f7a34794170a
 # ╟─4373ab10-d4e7-4e25-b7a8-da1fcf3dcb0c
+# ╠═77e467b9-c86c-4f13-a259-c38dfd80a3aa
 # ╠═f6e74270-bd75-4367-a0b2-1e10e1336b6c
 # ╠═091dbcb6-c5f6-469b-889a-e4b23197d2ad
 # ╠═c9bcf4b9-6769-4d5a-bbc0-a14675e11523