From e324104501ee53ea43f8bda956caa9f4c991c0e9 Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Tue, 22 Nov 2022 21:41:30 -0500 Subject: [PATCH 1/3] Add documentation --- .github/workflows/Documentation.yml | 47 ++++++++++++++++++ .gitignore | 5 ++ docs/Project.toml | 4 ++ docs/make.jl | 76 +++++++++++++++++++++++++++++ docs/src/assets/custom.css | 3 ++ docs/src/index.md | 12 +++++ docs/src/methods.md | 10 ++++ 7 files changed, 157 insertions(+) create mode 100644 .github/workflows/Documentation.yml create mode 100644 docs/Project.toml create mode 100644 docs/make.jl create mode 100644 docs/src/assets/custom.css create mode 100644 docs/src/index.md create mode 100644 docs/src/methods.md diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 0000000..8863b97 --- /dev/null +++ b/.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 diff --git a/.gitignore b/.gitignore index b6c10cc..aa26b25 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,7 @@ *~ Manifest.toml + +# Build artifacts for creating documentation generated by the Documenter package +docs/build/ +docs/site/ +docs/src/generated/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 0000000..063f7e1 --- /dev/null +++ b/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" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 0000000..c426c2b --- /dev/null +++ b/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 diff --git a/docs/src/assets/custom.css b/docs/src/assets/custom.css new file mode 100644 index 0000000..31e6549 --- /dev/null +++ b/docs/src/assets/custom.css @@ -0,0 +1,3 @@ +.docs-sourcelink { + opacity:1 !important; +} diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 0000000..57355d7 --- /dev/null +++ b/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. diff --git a/docs/src/methods.md b/docs/src/methods.md new file mode 100644 index 0000000..0f6c160 --- /dev/null +++ b/docs/src/methods.md @@ -0,0 +1,10 @@ +## Methods list + +```@index +``` + +## Methods usage + +```@autodocs +Modules = [MAT] +``` From 2d7333cd4a98e22ce0f4e2909e95688f0b44657a Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Tue, 22 Nov 2022 21:41:43 -0500 Subject: [PATCH 2/3] Tweak docstring --- src/MAT.jl | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/MAT.jl b/src/MAT.jl index e6c5824..c6f5079 100644 --- a/src/MAT.jl +++ b/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`. From 8646d19b36246c4905760181495b0e302eba5e4c Mon Sep 17 00:00:00 2001 From: Jeff Fessler Date: Tue, 22 Nov 2022 21:47:06 -0500 Subject: [PATCH 3/3] Add urls to readme --- README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/README.md b/README.md index 6262797..3189a21 100644 --- a/README.md +++ b/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 v5/v6/v7 format, as well as the newer v7.3 format. @@ -82,3 +85,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/). + + + +[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