Add Documenter documentation (JuliaIO#178)

* Add documentation

* Tweak docstring

* Add urls to readme

---------

Co-authored-by: Steve Kelly <[email protected]>

.github/workflows/Documentation.yml

@@ -0,0 +1,47 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths-ignore:
+      - 'README.md'
+  push:
+    paths-ignore:
+      - 'README.md'
+    branches:
+      - 'main'
+      - 'release-'
+    tags: '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: CacheArtifacts
+        uses: actions/cache@v3
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - name: InstallDependencies
+        run: |
+          julia --project=docs/ -e '
+            ENV["JULIA_PKG_SERVER"] = ""
+            using Pkg
+            Pkg.develop(PackageSpec(path=pwd()))
+            Pkg.instantiate()'
+      - name: BuildAndDeploy
+        env:
+# https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#Authentication:-GITHUB_TOKEN
+#         GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+        run: julia --project=docs/ docs/make.jl

.gitignore

@@ -1,2 +1,7 @@
 *~
 Manifest.toml
+
+# Build artifacts for creating documentation generated by the Documenter package
+docs/build/
+docs/site/
+docs/src/generated/

README.md

@@ -1,6 +1,9 @@
 # MAT.jl
 [![Build Status](https://github.com/JuliaIO/MAT.jl/workflows/CI/badge.svg?branch=master)](https://github.com/JuliaIO/MAT.jl/actions)
 
+[![docs-stable][docs-stable-img]][docs-stable-url]
+[![docs-dev][docs-dev-img]][docs-dev-url]
+
 ### Read and write MATLAB files in Julia
 
 This library can read MATLAB `.mat` files, both in the older v4/v5/v6/v7 format, as well as the newer v7.3 format.
@@ -91,3 +94,10 @@ close(file)
 ## Credits
 
 The MAT_HDF5 module, which provides read/write support for MATLAB v7.3 files, was written primarily by [Tim Holy](https://github.com/timholy/). The MAT_v5 module, which provides read support for MATLAB v5/v6/v7 files, was written primarily by [Simon Kornblith](https://github.com/simonster/). The MAT_v4 module, which provides read and write support for MATLAB v4 files, was written primarily by [Victor Saase](https://github.com/vsaase/).
+
+
+<!-- URLs -->
+[docs-stable-img]: https://img.shields.io/badge/docs-stable-blue.svg
+[docs-stable-url]: https://JuliaIO.github.io/MAT.jl/stable
+[docs-dev-img]: https://img.shields.io/badge/docs-dev-blue.svg
+[docs-dev-url]: https://JuliaIO.github.io/MAT.jl/dev

docs/Project.toml

@@ -0,0 +1,4 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"

docs/make.jl

@@ -0,0 +1,76 @@
+execute = isempty(ARGS) || ARGS[1] == "run"
+
+org, reps = :JuilaIO, :MAT
+eval(:(using $reps))
+using Documenter
+using Literate
+
+# https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@example-block
+ENV["GKSwstype"] = "100"
+ENV["GKS_ENCODING"] = "utf-8"
+
+# generate examples using Literate
+lit = joinpath(@__DIR__, "lit")
+src = joinpath(@__DIR__, "src")
+gen = joinpath(@__DIR__, "src/generated")
+
+base = "$org/$reps.jl"
+repo_root_url =
+    "https://github.com/$base/blob/main/docs/lit/examples"
+nbviewer_root_url =
+    "https://nbviewer.org/github/$base/tree/gh-pages/dev/generated/examples"
+binder_root_url =
+    "https://mybinder.org/v2/gh/$base/gh-pages?filepath=dev/generated/examples"
+
+
+repo = eval(:($reps))
+DocMeta.setdocmeta!(repo, :DocTestSetup, :(using $reps); recursive=true)
+
+for (root, _, files) in walkdir(lit), file in files
+    splitext(file)[2] == ".jl" || continue # process .jl files only
+    ipath = joinpath(root, file)
+    opath = splitdir(replace(ipath, lit => gen))[1]
+    Literate.markdown(ipath, opath; documenter = execute, # run examples
+        repo_root_url, nbviewer_root_url, binder_root_url)
+    Literate.notebook(ipath, opath; execute = false, # no-run notebooks
+        repo_root_url, nbviewer_root_url, binder_root_url)
+end
+
+
+# Documentation structure
+ismd(f) = splitext(f)[2] == ".md"
+pages(folder) =
+    [joinpath("generated/", folder, f) for f in readdir(joinpath(gen, folder)) if ismd(f)]
+
+isci = get(ENV, "CI", nothing) == "true"
+
+format = Documenter.HTML(;
+    prettyurls = isci,
+    edit_link = "main",
+    canonical = "https://$org.github.io/$repo.jl/stable/",
+    assets = ["assets/custom.css"],
+)
+
+makedocs(;
+    modules = [repo],
+    authors = "Contributors",
+    sitename = "$repo.jl",
+    format,
+    pages = [
+        "Home" => "index.md",
+        "Methods" => "methods.md",
+#       "Examples" => pages("examples")
+    ],
+)
+
+if isci
+    deploydocs(;
+        repo = "github.com/$base",
+        devbranch = "main",
+        devurl = "dev",
+        versions = ["stable" => "v^", "dev" => "dev"],
+        forcepush = true,
+        push_preview = true,
+        # see https://$org.github.io/$repo.jl/previews/PR##
+    )
+end

docs/src/assets/custom.css

@@ -0,0 +1,3 @@
+.docs-sourcelink {
+    opacity:1 !important;
+}

docs/src/index.md

@@ -0,0 +1,12 @@
+```@meta
+CurrentModule = MAT
+```
+
+# MAT.jl Documentation
+
+## Overview
+
+This Julia package
+[(MAT.jl)](https://github.com/JuliaIO/MAT.jl)
+provides tools
+for reading and writing MATLAB format data files in Julia.

docs/src/methods.md

@@ -0,0 +1,10 @@
+## Methods list
+
+```@index
+```
+
+## Methods usage
+
+```@autodocs
+Modules = [MAT]
+```

src/MAT.jl

@@ -109,10 +109,11 @@ end
     matopen(filename [, mode]; compress = false) -> handle
     matopen(f::Function, filename [, mode]; compress = false) -> f(handle)
 
-Mode defaults to "r" for read.  It can also be "w" for write, or "r+" for
-read or write without creation or truncation.
+Mode defaults to `"r"` for read.
+It can also be `"w"` for write,
+or `"r+"` for read or write without creation or truncation.
 
-Compression on reading is detected/handled automatically; the compress
+Compression on reading is detected/handled automatically; the `compress`
 keyword argument only affects write operations.
 
 Use with `read`, `write`, `close`, `keys`, and `haskey`.