Merge pull request #45 from JuliaMatrices/doc

Some documentation

.github/workflows/Documentation.yml

@@ -0,0 +1,43 @@
+name: Documentation
+
+on:
+  pull_request:
+  push:
+    branches:
+      - 'main'
+      - 'release-'
+    tags: '*'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1.6'
+      - name: Cache artifacts
+        uses: actions/cache@v1
+        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: Install dependencies
+        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 +1,29 @@
-/Manifest.toml
+# Files generated by invoking Julia with --code-coverage
+*.jl.cov
+*.jl.*.cov
+
+# Files generated by invoking Julia with --track-allocation
+*.jl.mem
+
+# System-specific files and directories generated by the BinaryProvider and BinDeps packages
+# They contain absolute paths specific to the host computer, and so should not be committed
+deps/deps.jl
+deps/build.log
+deps/downloads/
+deps/usr/
+deps/src/
+
+# Build artifacts for creating documentation generated by the Documenter package
+docs/build/
+docs/site/
+
+# File generated by Pkg, the package manager, based on a corresponding Project.toml
+# It records a fixed state of all packages used by the project. As such, it should not be
+# committed for packages, but should be committed for applications that require a static
+# environment.
+Manifest.toml
+
+# other
+.DS_Store
+.*.*.swp
+.benchmarkci

README.md

@@ -6,11 +6,11 @@
 
 A [Julia](http://julialang.org) package for working with special matrix types.
 
-This package extends the `LinearAlgebra` library with support for special
+This Julia package extends the `LinearAlgebra` library with support for special
 matrices which are used in linear algebra. Every special matrix has its own type.
 The full matrix is accessed by the command `Matrix(A)`.
 
-The package is registered and can be installed by running:
+## Installation
 
 ```julia
 julia> ] add SpecialMatrices
@@ -21,6 +21,7 @@ julia> ] add SpecialMatrices
 [ToeplitzMatrices.jl](https://github.com/JuliaMatrices/ToeplitzMatrices.jl) supports
 Toeplitz, Hankel, and circulant matrices.
 
+
 ## Currently supported special matrices
 
 ### [`Cauchy` matrix](http://en.wikipedia.org/wiki/Cauchy_matrix)

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+
+[compat]
+Documenter = "0.27.3"
+Literate = "2"

docs/lit/examples/1-overview.jl

@@ -0,0 +1,16 @@
+#---------------------------------------------------------
+# # [SpecialMatrices overview](@id 1-overview)
+#---------------------------------------------------------
+
+# This page illustrates the Julia package
+# [`SpecialMatrices`](https://github.com/JuliaMatrices/SpecialMatrices.jl).
+
+# ### Setup
+
+# Packages needed here.
+
+using SpecialMatrices
+
+# ### Cauchy
+
+Cauchy(collect(1:3), collect(2:4))

docs/make.jl

@@ -0,0 +1,67 @@
+using SpecialMatrices
+using Documenter
+using Literate
+
+# based on:
+# https://github.com/jw3126/UnitfulRecipes.jl/blob/master/docs/make.jl
+
+# https://juliadocs.github.io/Documenter.jl/stable/man/syntax/#@example-block
+ENV["GKSwstype"] = "100"
+
+# generate tutorials and how-to guides using Literate
+lit = joinpath(@__DIR__, "lit")
+src = joinpath(@__DIR__, "src")
+notebooks = joinpath(src, "notebooks")
+
+ENV["GKS_ENCODING"] = "utf-8"
+
+DocMeta.setdocmeta!(SpecialMatrices, :DocTestSetup, :(using SpecialMatrices); recursive=true)
+
+execute = true # Set to true for executing notebooks and documenter!
+nb = false # Set to true to generate the notebooks
+for (root, _, files) in walkdir(lit), file in files
+    splitext(file)[2] == ".jl" || continue
+    ipath = joinpath(root, file)
+    opath = splitdir(replace(ipath, lit=>src))[1]
+    Literate.markdown(ipath, opath, documenter = execute)
+    nb && Literate.notebook(ipath, notebooks, execute = execute)
+end
+
+# Documentation structure
+ismd(f) = splitext(f)[2] == ".md"
+pages(folder) =
+    [joinpath(folder, f) for f in readdir(joinpath(src, folder)) if ismd(f)]
+
+isci = get(ENV, "CI", nothing) == "true"
+
+format = Documenter.HTML(;
+    prettyurls = isci,
+    edit_link = "main",
+    canonical = "https://JuliaMatrices.github.io/SpecialMatrices.jl/stable/",
+#   assets = String[],
+)
+
+makedocs(;
+    modules = [SpecialMatrices],
+    sitename = "SpecialMatrices.jl",
+    format,
+    pages = [
+        "Home" => "index.md",
+        "Methods" => "methods.md",
+        "Examples" => pages("examples")
+    ],
+)
+
+if isci
+    deploydocs(;
+        repo = "github.com/JuliaMatrices/SpecialMatrices.jl",
+        devbranch = "main",
+        devurl = "dev",
+        versions = ["stable" => "v^", "dev" => "dev"],
+        forcepush = true,
+        push_preview = true,
+        # see https://JuliaMatrices.github.io/SpecialMatrices.jl/previews/PR##
+    )
+else
+    @warn "may need to: rm -r src/examples"
+end

docs/src/index.md

@@ -0,0 +1,19 @@
+```@meta
+CurrentModule = SpecialMatrices
+```
+
+# SpecialMatrices.jl Documentation
+
+## Overview
+
+This Julia module exports methods for defining
+special matrices
+that are used in linear algebra.
+Every special matrix has its own type. 
+
+(This documentation is under construction).
+
+See the package README
+for details.
+
+See the Examples.

docs/src/methods.md

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