diff --git a/README.md b/README.md index 148aa15..a82f509 100644 --- a/README.md +++ b/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 diff --git a/docs/make.jl b/docs/make.jl index 640eff5..cdddfdc 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -16,6 +16,8 @@ makedocs(; ), pages=[ "Home" => "index.md", + "Reference" => "ref.md", + "Extending" => "extend.md", ], ) diff --git a/docs/src/extend.md b/docs/src/extend.md new file mode 100644 index 0000000..c5408c8 --- /dev/null +++ b/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 +``` diff --git a/docs/src/index.md b/docs/src/index.md index a74af77..e4a9beb 100644 --- a/docs/src/index.md +++ b/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 ``` diff --git a/docs/src/ref.md b/docs/src/ref.md new file mode 100644 index 0000000..efc02d8 --- /dev/null +++ b/docs/src/ref.md @@ -0,0 +1,11 @@ + +```@meta +CurrentModule = DataViewer +``` + +# Reference for the user-facing API + +```@docs +view +install +``` diff --git a/docs/src/screencast.mp4 b/docs/src/screencast.mp4 new file mode 100644 index 0000000..488026f Binary files /dev/null and b/docs/src/screencast.mp4 differ diff --git a/src/DataViewer.jl b/src/DataViewer.jl index bdb6bf6..87ffea7 100644 --- a/src/DataViewer.jl +++ b/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