Documentation site update (#393)

* Rename make_docs.jl

make_docs.jl only deals with the registry, so rename to
populat_registry.jl

* Use Documenter.jl v1 to build documentation site

* Add method and type headers to docstrings

* Add fence language tags

* Remove REPL prompt from install instructions

The code is more likely to be copy-pasted

* Export info

`info()` is listed in FileIO module docstring

* Wrap lines

* Add Downloads to test dependencies

Base.download() is deprecated

* Add markdown ref links to types and methods

* Loosen Downloads compat for tests

* Revert "Export info"

This reverts commit 037496a.

* Add docstring for info() to API reference page

* Reformat docstring for stream()

---------

Co-authored-by: Nathan Zimmerberg <[email protected]>

Author: abhro

Project.toml

@@ -16,6 +16,7 @@ Aqua = "0.8"
 CSVFiles = "1"
 CodecZlib = "0.5, 0.6, 0.7"
 ColorTypes = "0.11"
+Downloads = "1.4"
 FilePathsBase = "0.9"
 HTTP = "0.6, 1"
 Random = "<0.0.1, 0.7, 1"
@@ -26,10 +27,11 @@ Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 CSVFiles = "5d742f6a-9f54-50ce-8119-2520741973ca"
 CodecZlib = "944b1d66-785c-5afd-91f1-9de20f533193"
 ColorTypes = "3da002f7-5984-5a60-b8a6-cbb66c0b333f"
+Downloads = "f43a241f-c20a-4ad4-852c-f6b1247861c6"
 FilePathsBase = "48062228-2e41-5def-b9a4-89aafe57970f"
 HTTP = "cd3eb016-35fb-5094-929b-558a96fad6f3"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
-test = ["Aqua", "ColorTypes", "CodecZlib", "CSVFiles", "FilePathsBase", "HTTP", "Random", "Test"]
+test = ["Aqua", "ColorTypes", "CodecZlib", "CSVFiles", "Downloads", "FilePathsBase", "HTTP", "Random", "Test"]

docs/make.jl

@@ -1,7 +1,7 @@
 using Documenter
 using FileIO
 
-include("make_docs.jl")
+include("populate_registry.jl")
 
 makedocs(
     sitename = "FileIO",

docs/make_docs.jl renamed to docs/populate_registry.jl

@@ -90,7 +90,7 @@ fs = open(joinpath(pkgdir(FileIO), "docs", "src", "registry.md"), "w")
 
     println(fs, """
     | Format Name | extensions | IO library | detection or magic number |
-    | ----------- | ---------- | ---------- | ---------- |""")
+    | ----------- | ---------- | ---------- | ------------------------- |""")
     include(joinpath(pkgdir(FileIO), "src", "registry.jl"))
 
 close(fs)

docs/src/implementing.md

@@ -87,7 +87,7 @@ closing any streams you opened in order to read or write the file. If you are
 given a `Stream`, your `close` method should only do the clean up for your
 reader or writer type, not close the stream.
 
-```jl
+```julia
 struct WAVReader
     io::IO
     ownstream::Bool

docs/src/index.md

@@ -13,9 +13,8 @@ provide support for standard file formats through functions named
 Install FileIO within Julia via
 
 ```julia
-julia> using Pkg
-
-julia> Pkg.add("FileIO")
+using Pkg
+Pkg.add("FileIO")
 ```
 
 ## Usage

docs/src/reference.md

@@ -4,3 +4,6 @@
 Modules = [FileIO]
 Private = false
 ```
+```@docs
+FileIO.info
+```

docs/src/registering.md

@@ -14,7 +14,7 @@ You'll need to [`pkg> dev FileIO`](https://julialang.github.io/Pkg.jl/v1/managin
 Before going into detail explaining the arguments of `add_format`,
 here is a real example that could be used to register an I/O package for one of the [Netpbm image formats](https://en.wikipedia.org/wiki/Netpbm#File_formats):
 
-```
+```julia
 add_format(format"PPMBinary", "P6", ".ppm", [:Netpbm => UUID("f09324ee-3d7c-5217-9330-fc30815ba969")])
 ```
 

docs/src/world_age_issue.md

@@ -13,7 +13,7 @@ thing related to image IO.
 To avoid such unnecessary loading latency, FileIO defers package loading until it's actually used.
 For instance, when you use FileIO, you'll probably observe something like this:
 
-```julia
+```julia-repl
 julia> using TestImages, FileIO
 
 julia> path = testimage("cameraman"; download_only=true)
@@ -38,20 +38,20 @@ after initial compilation finishes) than the one you called them from.
 Let's demonstrate the problem concretely. In case you don't have a suitable file to play with, let's
 first create one:
 
-```julia
+```julia-repl
 julia> using IndirectArrays, ImageCore
 
 julia> img = IndirectArray(rand(1:5, 4, 4), rand(RGB, 5))
 4×4 IndirectArray{RGB{Float64}, 2, Int64, Matrix{Int64}, Vector{RGB{Float64}}}:
-...
+[...]
 
 julia> save("indexed_image.png", img)
 ```
 
 Now, **reopen a new julia REPL** (this is crucial for demonstrating the problem) and call `load`
 from **within a function** (this is also crucial):
 
-```julia
+```julia-repl
 julia> using FileIO
 
 julia> f() = size(load("indexed_image.png"))
@@ -95,7 +95,7 @@ which you called `f()`. This leads to the observed error.
 
 The good news is it's easy to fix, just try calling `f()` again:
 
-```julia
+```julia-repl
 julia> f()
 (4, 4)
 ```
@@ -113,7 +113,7 @@ around this world-age dispatch problem. Literally, `invokelatest` dispatches the
 the latest world age (which may be newer than when you typed `f()` at the REPL). **In a fresh Julia
 session**,
 
-```julia
+```julia-repl
 julia> using FileIO
 
 julia> f() = Base.invokelatest(size, load("indexed_image.png"))
@@ -138,7 +138,7 @@ Another solution to the world age issue is simple and doesn't have long-term dow
 load the needed packages**. For instance, if you're seeing world age issue complaining methods
 related to `IndirectArray`, then load IndirectArrays eagerly:
 
-```julia
+```julia-repl
 julia> using FileIO, IndirectArrays # try this on a new Julia REPL
 
 julia> f() = size(load("indexed_image.png"))

src/FileIO.jl

@@ -41,26 +41,26 @@ include("registry.jl")
 `FileIO` API (brief summary, see individual functions for more detail):
 
 - `format"PNG"`: specifies a particular defined format
-- `File{fmt}` and `Stream{fmt}`: types of objects that declare that a resource has a particular format `fmt`
+- [`File{fmt}`](@ref) and [`Stream{fmt}`](@ref): types of objects that declare that a resource has a particular format `fmt`
 
-- `load([filename|stream])`: read data in formatted file, inferring the format
+- [`load([filename|stream])`](@ref): read data in formatted file, inferring the format
 - `load(File{format"PNG"}(filename))`: specify the format manually
-- `loadstreaming([filename|stream])`: similar to `load`, except that it returns an object that can be read from
-- `save(filename, data...)` for similar operations involving saving data
-- `savestreaming([filename|stream])`: similar to `save`, except that it returns an object that can be written to
+- [`loadstreaming([filename|stream])`](@ref): similar to `load`, except that it returns an object that can be read from
+- [`save(filename, data...)`](@ref) for similar operations involving saving data
+- [`savestreaming([filename|stream])`](@ref): similar to `save`, except that it returns an object that can be written to
 
 - `io = open(f::File, args...)` opens a file
-- `io = stream(s::Stream)` returns the IOStream from the query object `s`
+- [`io = stream(s::Stream)`](@ref stream) returns the IOStream from the query object `s`
 
-- `query([filename|stream])`: attempt to infer the format of `filename`
-- `unknown(q)` returns true if a query can't be resolved
-- `skipmagic(io, fmt)` sets the position of `io` to just after the magic bytes
-- `magic(fmt)` returns the magic bytes for format `fmt`
-- `info(fmt)` returns `(magic, extensions)` for format `fmt`
+- [`query([filename|stream])`](@ref): attempt to infer the format of `filename`
+- [`unknown(q)`](@ref) returns true if a query can't be resolved
+- [`skipmagic(io, fmt)`](@ref) sets the position of `io` to just after the magic bytes
+- [`magic(fmt)`](@ref) returns the magic bytes for format `fmt`
+- [`info(fmt)`](@ref) returns `(magic, extensions)` for format `fmt`
 
-- `add_format(fmt, magic, extension, libraries...)`: register a new format
-- `add_loader(fmt, :Package)`: indicate that `Package` supports loading files of type `fmt`
-- `add_saver(fmt, :Package)`: indicate that `Package` supports saving files of type `fmt`
+- [`add_format(fmt, magic, extension, libraries...)`](@ref): register a new format
+- [`add_loader(fmt, :Package)`](@ref): indicate that `Package` supports loading files of type `fmt`
+- [`add_saver(fmt, :Package)`](@ref): indicate that `Package` supports saving files of type `fmt`
 """
 FileIO
 

src/error_handling.jl

@@ -1,7 +1,11 @@
 """
+    LoaderError <: Exception
+
 `LoaderError` should be thrown when loader library code fails, and other libraries should
 be given the chance to recover from the error.  Reports the library name and an error message:
+```julia
 LoaderError("ImageMagick", "Foo not available")
+```
 """
 struct LoaderError <: Exception
     library::String
@@ -12,9 +16,13 @@ Base.showerror(io::IO, e::LoaderError) = println(IOContext(io, :limit=>true), e.
                                                  e.msg, "\n  due to ", e.ex, "\n  Will try next loader.")
 
 """
+    WriterError <: Exception
+
 `WriterError` should be thrown when writer library code fails, and other libraries should
 be given the chance to recover from the error.  Reports the library name and an error message:
+```julia
 WriterError("ImageMagick", "Foo not available")
+```
 """
 struct WriterError <: Exception
     library::String
@@ -34,6 +42,8 @@ end
 Base.showerror(io::IO, e::SpecError) = print(io, e.mod, " is missing $(e.call) and fileio_$(e.call)")
 
 """
+    handle_exceptions(exceptions::Vector, action)
+
 Handles a list of thrown errors after no IO library was found working
 """
 function handle_exceptions(exceptions::Vector, action)