Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Documenter documentation #178

Merged
merged 4 commits into from
Jun 7, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/Documentation.yml
Original file line number Diff line number Diff line change
@@ -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
5 changes: 5 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,7 @@
*~
Manifest.toml

# Build artifacts for creating documentation generated by the Documenter package
docs/build/
docs/site/
docs/src/generated/
10 changes: 10 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down Expand Up @@ -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
4 changes: 4 additions & 0 deletions docs/Project.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
[deps]
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
76 changes: 76 additions & 0 deletions docs/make.jl
Original file line number Diff line number Diff line change
@@ -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
3 changes: 3 additions & 0 deletions docs/src/assets/custom.css
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
.docs-sourcelink {
opacity:1 !important;
}
12 changes: 12 additions & 0 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -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.
10 changes: 10 additions & 0 deletions docs/src/methods.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
## Methods list

```@index
```

## Methods usage

```@autodocs
Modules = [MAT]
```
7 changes: 4 additions & 3 deletions src/MAT.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand Down