Merge pull request #27 from disberd/add_docs

Add documentation

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.9'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -1,2 +1,4 @@
 Manifest.toml
-test*.jl
+test*.jl
+*.jlcov
+docs/build/

README.md

@@ -1,54 +1,13 @@
 # PlutoExtras
+[![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://disberd.github.io/PlutoExtras.jl/)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://disberd.github.io/PlutoExtras.jl/dev)
 [![Build Status](https://github.com/disberd/PlutoExtras.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/disberd/PlutoExtras.jl/actions/workflows/CI.yml?query=branch%3Amaster)
 [![Coverage](https://codecov.io/gh/disberd/PlutoExtras.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/disberd/PlutoExtras.jl)
 
 This package provides some widgets to be used in Pluto, including an extended version of the TableOfContents from PlutoUI and a new experimental bond container (`BondTable`). 
 
-This was formerly a non-registered package named PlutoUtils
+See the [documentation](https://disberd.github.io/PlutoExtras.jl/) for more details.
 
+This was formerly a non-registered package named PlutoUtils
+## Note
 To check out the functionalities in more detail, check the notebooks located in the test folder at [test/notebooks](./test/notebooks/) (You have to execute them from their original folder within the package folder, or the loading of the package with `@frompackage` will fail.)
-
-## BondTable (NEW!)
-
-There is some new under-development experimental feature to simplify the grouping and displaying of many bonds within a given notebook in a floating table (similar to the TableOfContents) that stays on the left and can be hidden, resized and moved around.
-
-Have a look at the notebook at [notebooks/test_bondstable.jl](https://rawcdn.githack.com/disberd/PlutoExtras.jl/5b57bbb25276ff44cd79e93b72b8c504fd46a432/html_exports/test_bondstable.jl.html) for an example of the features/capabilities. (The link points to a static html export of the notebook. If you want to execute the notebook, remember that it has to be executed from the cloned repository as it currently uses the package environment of the package)
-
-## ExtendedTableOfContents
-The [extended_toc.jl](./test/notebooks/extended_toc.jl) notebook shows the example use of `ExtendedTableOfContents`, which takes the `TableOfContents` from `PlutoUI` and adds the following functionalities:
-
-### 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
-
-
-### Example usage
-
-#### 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)
-

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+PlutoExtras = "ed5d0301-4775-4676-b788-cf71e66ff8ed"

docs/make.jl

@@ -0,0 +1,38 @@
+using PlutoExtras
+using PlutoExtras.StructBondModule
+using Documenter
+
+DocMeta.setdocmeta!(PlutoExtras, :DocTestSetup, :(using PlutoExtras); recursive=true)
+
+makedocs(;
+    modules= Module[],
+    authors="Alberto Mengali <[email protected]>",
+    repo="https://github.com/disberd/PlutoExtras.jl/blob/{commit}{path}#{line}",
+    sitename="PlutoExtras.jl",
+    format=Documenter.HTML(;
+        prettyurls=get(ENV, "CI", "false") == "true",
+        edit_link="master",
+        assets=String[],
+    ),
+    pages=[
+        "index.md",
+        "basic_widgets.md",
+        "latex_equations.md",
+        "toc.md",
+        "structbond.md",
+    ],
+)
+
+# This controls whether or not deployment is attempted. It is based on the value
+# of the `SHOULD_DEPLOY` ENV variable, which defaults to the `CI` ENV variables or
+# false if not present.
+should_deploy = get(ENV,"SHOULD_DEPLOY", get(ENV, "CI", "") === "true")
+
+if should_deploy
+    @info "Deploying"
+
+deploydocs(
+    repo = "github.com/disberd/PlutoExtras.jl.git",
+)
+
+end

docs/src/basic_widgets.md

@@ -0,0 +1,12 @@
+# Basic Widgets
+This Package exports two basic widgets: `Editable` and `StringOnEnter`
+
+## Editable
+```@docs
+Editable
+```
+
+## StringOnEnter
+```@docs
+StringOnEnter
+```

docs/src/index.md

@@ -0,0 +1,14 @@
+# PlutoExtras
+
+Documentation for [PlutoExtras](https://github.com/disberd/PlutoExtras.jl).
+
+## Outline
+```@contents
+Pages = [
+    "basic_widgets.md",
+    "latex_equations.md",
+    "toc.md",
+    "structbond.md",
+]
+Depth = 1
+```

docs/src/latex_equations.md

@@ -0,0 +1,34 @@
+# LaTeX Equations
+PlutoExtras provides some convenience functions to display numbered equations using [KaTeX](https://katex.org).
+The use of KaTeX as opposed to Mathjax as in Markdown is that complex interpolation of Julia variables work better and automatic equation numbering based on the cell position in the notebook is possible.
+
+KaTeX [supports](https://katex.org/docs/supported.html) automatic numbering of
+*equation* environments.  While it does not support equation reference and
+labelling, [this](https://github.com/KaTeX/KaTeX/issues/2003) hack on github
+shows how to achieve the label functionality.
+
+Unfortunately, since automatic numbering in KaTeX uses CSS counters, it is not
+possible to access the value of the counter at a specific DOM element.  We then
+create a function that loops through all possible katex equation and counts
+them, putting the relevant number in the appropriate hyperlink innerText to
+create equation references that automatically update.
+
+If one wants the exploit equation referencing with automatic numbering update, this functionality **must be initialized** by having a cell which calls [`initialize_eqref`](@ref) as its last statement (so that the javascript code it generates is sent to the cell output)
+
+## Example
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264626063-1dd7ca9b-9463-4e27-b1ac-d8b2a860ea9b.mp4" type="video/mp4">
+</video>
+```
+Open the [latex test notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/latex_equations.jl) to check this functionality in action!
+
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
+## API
+```@docs
+initialize_eqref
+texeq
+@texeq_str
+eqref
+```

docs/src/structbond.md

@@ -0,0 +1,110 @@
+# 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`
+
+Open the [structbond test notebook static html](https://rawcdn.githack.com/disberd/PlutoExtras.jl/0e3153d29d3b112f93507c042a35b8161a3bb661/html_exports/test_bondstable.jl.html) to see the look of the widgets exported.\
+Or open the [related notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/structbondmodule.jl) directy in Pluto to check their functionality in action!
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
+
+## StructBond
+Generating automatic widgets for custom structs is quite straightforward with
+the aid of the [`@fielddata`](@ref) macro and the [`StructBond`](@ref) type.
+
+The `StructBond` structure wraps another structure and generates a widget that can be used together with `@bind` to obtain instances of a custom structure.
+In order to correctly display the widget, the description and widget associated to each field of the structure must be specified either.
+
+This can be done either using [`@fielddata`](@ref) as in the example video below or by using the separate [`@fieldbond`](@ref) and [`@fielddescription`](@ref) separately.
+
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264639467-ecda1c22-141a-4297-98d7-0667d2e8d5a4.mp4" type="video/mp4">
+</video>
+```
+
+## @NTBond
+Sometimes custom structs are not needed and it would be useful to just use the same nice bond structure of [`StructBond`](@ref) to simply create arbitrary NamedTuples. 
+
+This is possible with the convenience macro [`@NTBond`](@ref) which can be called as shown below to create a nice display for an interactive bond creating an arbitrary NamedTuple.
+
+The macro simply create a [`StructBond`](@ref) wrapping the desired NamedTuple type.
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264640510-c605d3af-77c8-4752-9b80-8bc85545d566.mp4" type="video/mp4">
+</video>
+```
+
+## @BondsList
+In some cases, one does not want to have a single bond wrapping either a Structure or a NamedTuple because single independent bonds are more convenient.
+
+[`@BondsList`](@ref) is a convenience macro to create an object of type [`BondsList`](@ref) which simply allow to add a description to separate bonds and group them all together in a table-like format equivalent to those of [`StructBond`](@ref).
+
+!!! note
+	Unlike [`StructBond`](@ref), a BondsList is already composed of bond created with [`@bind`](@ref) and it just groups them up with a description. The output of [`@BondsList`](@ref) is not supposed to be bound to a variable using [`@bind`](@ref).\
+	The bonds grouped in a BondsList still act and update independently from one another.
+
+See the example below for understanding the synthax. The header of a BondsList is shown in an orange background to easily differentiate it from [`StructBond`](@ref).
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264641605-7ab58c12-2c30-47c3-a93a-d64784c34a71.mp4" type="video/mp4">
+</video>
+```
+
+## Popout/popoutwrap
+The structures above can also be used nested within one another. To facilitate accessing nested structures, one can use the [`Popout`](@ref) type.
+
+In its simple form, you can give an instance of a StructBond, a bond wrapping a StructBond or a BondsList as input to Popout to create a table that is hidden behind a popup window.
+If an instance present, but you want a custom type for which you have defined custom bonds and descriptions with [`@fielddata`](@ref) to appear as popout, you can use the function `popoutwrap(TYPE)` to generate a small icon which hides a popup containing the [`StructBond`](@ref) of the provided type `TYPE`.
+
+The StructBond table appears on hover upon the icon, can be made fixed by clicking on the icon and can then be moved around or resized.
+A double click on the header of the popout hides it again:
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264643126-cdf19078-70cb-46e2-aeb0-304a05ecf08a.mp4" type="video/mp4">
+</video>
+```
+
+The ability to also wrap pre-existing bonds around StructBonds is convenient for organizing the various bonds one have in a [`BondsList`](@ref) or [`BondTable`](@ref)
+
+As an example, one can create a [`BondsList`](@ref) containing the two [`StructBond`](@ref) bonds generated at the beginning of this notebook (the videos in the [structbond section above](#StructBond)) like in the following example:
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264645841-263f0cb3-ac79-4fe2-b66a-f8d5a4a70896.mp4" type="video/mp4">
+</video>
+```
+
+## BondTable
+The final convenience structure provided by this module is the [`BondTable`](@ref). It can be created to group a list of bonds in a floating table that stays on the left side of the notebook (similar to the TableOfContents of PlutoUI) and can be moved around and resized or hidden for convenience.
+
+The BondTable is intended to be used either with bonds containing [`StructBond`](@ref) or with [`BondsList`](@ref). Future types with similar structure will also be added.
+
+Here is an example of a bondtable containing all the examples seen so far.
+```@raw html
+<video controls=true>
+<source src="https://user-images.githubusercontent.com/12846528/264646632-8c1b3eed-1adf-434b-925a-d57b99fc3c29.mp4" type="video/mp4">
+</video>
+```
+
+## API
+
+### Main
+```@docs
+StructBondModule.StructBond
+StructBondModule.@fielddata
+StructBondModule.@NTBond
+StructBondModule.@BondsList
+StructBondModule.popoutwrap
+StructBondModule.BondTable
+```
+
+### Secondary/Advanced
+```@docs
+StructBondModule.@fieldbond
+StructBondModule.@fielddescription
+StructBondModule.Popout
+StructBondModule.@popoutasfield
+StructBondModule.@typeasfield
+```

docs/src/toc.md

@@ -0,0 +1,52 @@
+# 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
+Open the [extended ToC test notebook](https://github.com/disberd/PlutoExtras.jl/blob/master/test/notebooks/extended_toc.jl) to check this functionality in action!
+!!! note
+    The notebook must be run from the original folder (`test/notebooks`) within the `PlutoExtras` package folder to properly load the PlutoExtras package
+
+### 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
+```