Updated documentation

docs/make.jl

 using Documenter, BDIO
 
-makedocs(modules=[BDIO], doctest=true, sitename = "BDIO meets Julia")
+makedocs(modules=[BDIO], doctest=true,
+         sitename = "BDIO meets Julia",
+         repo = "https://gitlab.ift.uam-csic.es/alberto/bdio.jl")
 
 deploydocs(deps   = Deps.pip("mkdocs", "python-markdown-math"),
-           repo = "https://gitlab.ift.uam-csic.es/alberto/bdio.jl",
-           julia  = "1.1.1",
-           osname = "FreeBSD")
+           repo = "gitlab.ift.uam-csic.es/alberto/bdio.jl")
 

docs/src/index.md

@@ -4,11 +4,79 @@ This package provides an interface to read/write
 [BDIO](http://bdio.org/) (**B**inary **D**ata **I**nput/**O**utput)
 files in Julia. 
 
-## Index
+## Getting started
 
-```@index
+Here we write a file with two records:
+- A record of type `BDIO_BIN_INT64LE` that contains the first 1000 numbers. This record has user info 1.
+- A record of type `BDIO_BIN_F64LE` that contains a total of 2000 numbers: 1000 random numbers and then the same numbers with opposite sign. This record has user info 2. Note that writing data to a record can be done with more than one call to `BDIO_write!`. 
+
+The `MD5` sum of both records is stored in the same `BDIO` file thanks
+to the calls to `BDIO_write_hash!`. These are written in special
+`BDIO` records themselves, with user info 7. 
+
+```@repl
+using BDIO
+BDIO_set_user("alberto")
+BDIO_set_host("laptop")
+fb  = BDIO_open("foo.bdio", "w", "Test file")
+BDIO_start_record!(fb, BDIO_BIN_INT64LE, 1, true)
+BDIO_write!(fb, collect(1:1000))
+BDIO_write_hash!(fb)
+BDIO_start_record!(fb, BDIO_BIN_F64LE, 2, true)
+vec1  = randn(1000);
+vec2  = similar(vec1);
+vec2 .= .- vec1;
+BDIO_write!(fb, vec1)
+BDIO_write!(fb, vec2)
+BDIO_write_hash!(fb)
+BDIO_close!(fb)
+```
+
+In total the file has 4 records (2 data records, 2 checksum
+records). We can see the contents using the [`lsbdio`
+tool](http://bdio.org/). 
+
+```
+┌─(Wed Jul  1 09:32:00 2020)──[localhost]──[/u/h/a/c/j/B/docs/src]
+└─> $ lsbdio foo.bdio 
+ID     record type       size   uinf starts with                           long
+0      header v 1          alberto@laptop           Wed Jul  1 09:31:24 2020   
+1      record i64 le    8000 byte  1 1 2 3 4 5 6 7 8 9 10 11 12 13            x
+2      record MD5-h       20 byte  7 F41BD4FBFC77E5D5ABDF7300F42C1591         -
+3      record f64 le   16000 byte  2 1.378609e-01 -2.838856e-01               x
+4      record MD5-h       20 byte  7 1A5636335356BB004E489AB5DAE89B5D         -
 ```
 
+Now let's read the data. We travel the file using `BDIO_seek!` until
+we find the records that we are looking for: user info 1 for the
+integer data and user info 2 for the real data. Again note that
+reading a single record can be done in chunks with multiple calls to
+`BDIO_read`. 
+
+
+```@repl
+using BDIO
+fb2 = BDIO_open("foo.bdio", "r")
+global isum = 0
+global fsum = 0.0
+while BDIO_seek!(fb2)
+    if BDIO_get_uinfo(fb2) == 1
+        idt = similar(Array{Int64,   1}, 100)
+        for i = 1:10
+            BDIO_read(fb2, idt)
+            global isum += sum(idt)
+        end
+    elseif BDIO_get_uinfo(fb2) == 2
+        fdt = similar(Array{Float64, 1}, 100)
+        for i = 1:20
+            BDIO_read(fb2, fdt)
+            global fsum += sum(fdt)
+        end
+    end
+end
+println("Better be zero: ", fsum)
+println("Better be zero: ", (2*isum - 1000*1001))
+```
 
 ## Setting up global information
 
@@ -47,3 +115,8 @@ BDIO_get_len
 BDIO_get_fmt
 ```
 
+## Index
+
+```@index
+```
+