Improved documentation

README.md

@@ -7,7 +7,7 @@
 
 **Explore your data files with the power of [Makie](https://docs.makie.org/stable/)!**
 
-![](docs/screencast.gif)
+![](docs/src/screencast.mp4)
 
 ## Use as a Julia package
 

docs/make.jl

@@ -16,6 +16,8 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Reference" => "ref.md",
+        "Extending" => "extend.md",
     ],
 )
 

docs/src/extend.md

@@ -0,0 +1,14 @@
+```@meta
+CurrentModule = DataViewer
+```
+
+# Extending `DataViewer` to support more data formats
+
+```@docs
+recurse_into
+filetype
+open_datafile
+graphic_repr
+get_data
+pretty_repr
+```

docs/src/index.md

@@ -6,9 +6,96 @@ CurrentModule = DataViewer
 
 Documentation for [DataViewer](https://github.com/triscale-innov/DataViewer.jl).
 
-```@index
+![](screencast.mp4)
+
+
+## Installation
+
+`DataViewer` is not registered (yet), so you need to provide its full URL to the Julia package manager.
+
+```julia-repl
+julia> ] # enter Pkg mode
+pkg> add https://github.com/triscale-innov/DataViewer.jl.git
+```
+
+Since `DataViewer` requires a lot of heavy dependencies, it is not advised to
+add it to the default environment. One possibility would be to create a
+dedicated named environment:
+
+```julia-repl
+julia> ] # enter Pkg mode
+(@v1.9) pkg> activate @dataviewer
+(@dataviewer) pkg> add https://github.com/triscale-innov/DataViewer.jl.git
+```
+
+## Use as a Julia package
+
+`DataViewer` can be used as a regular package from inside a Julia REPL. Whenever
+there is some data structure that you want to explore, call the [`view`](@ref) function:
+```julia-repl
+julia> using JLD2
+
+julia> data = JLD2.load("sample.jld2");
+
+julia> using DataViewer
+[ Info: Precompiling DataViewer [69fa7e04-3a55-42d6-bb08-3ca48704fbef]
+[ Info: Precompiling JSON_Ext [056fc32c-03f3-5092-ad64-0a1590c5cd8d]
+[ Info: Precompiling JLD2_Ext [ab4143e6-3402-5971-8428-17ae5f4067b4]
+
+julia> DataViewer.view(data)
+```
+
+It is also possible to directly call [`view`](@ref) on a file name:
+```julia-repl
+julia> using HDF5
+[ Info: Precompiling HDF5_Ext [c89765bd-c6f5-5c69-b5b2-135d132d13bc]
+
+julia> DataViewer.view("sample.h5")
+```
+
+!!! note
+
+    In this case, you'll need to first load the appropriate package for the file
+    format you want to read: `HDF5`, `JLD2` or `JSON`.
+
+## Use as a standalone application
+
+After having installed the `DataViewer` package, you can ask it to
+[`install`](@ref) a standalone application, callable from the command-line:
+
+```julia-repl
+julia> using DataViewer
+
+julia> DataViewer.install()
+```
+
+By default, a launcher named `dataviewer` will be placed in the `~/.julia/bin`
+directory, which you should add to your `PATH` environment variable. Afterwards,
+you can run this new command from a shell.
+
+!!! note
+
+    Windows users may want to run something like:
+
+    ```
+    julia> DataViewer.install(destdir = joinpath(homedir(), "Desktop"))
+    ```
+
+    in order to put the launcher on their desktop.
+
+Without argument, a file picker window will pop up to ask for a file to open:
+```shell
+$ dataviewer
+```
+
+With one argument, the given file will be viewed:
+```shell
+$ dataviewer sample.hdf5
 ```
 
-```@autodocs
-Modules = [DataViewer]
+A second argument allows specifying the file type if the extension is not enough
+to guess it. This optional argument may be either the name of the relevant Julia
+package (*e.g* `JSON`) or a file extension associated to the file format (*e.g* `.json`):
+```shell
+$ dataviewer sample JSON
 ```

docs/src/ref.md

@@ -0,0 +1,11 @@
+
+```@meta
+CurrentModule = DataViewer
+```
+
+# Reference for the user-facing API
+
+```@docs
+view
+install
+```

src/DataViewer.jl

@@ -121,8 +121,12 @@ view(data, name::String = "") = Internal.view(data, name)
 """
     view(fname::String, ftype = "")
 
-Open a viewer window for the data contained in file `fname`. The extension of
-`fname` is used to determine how to read it.
+Open a viewer window for the data contained in file `fname`.
+
+The extension of `fname` is normally used to determine how to read it. But the
+optional argument `ftype` may be provided to override this behavior. In this
+case, `ftype` should be a file extension associated to the file format (for
+example: `".jld2"` for JLD2 files).
 
 Because the file may need to be accessed during the whole browsing session, this
 function does not return until the window has been closed, at which point the