Set up documenter (#148)

* Ignore docs build directory

* Add docs build action

* More docs setup

* Ignore docs manifest

* Fix doctest

* Fix branches

* Fix Julia version

* Tweak and re-run

* Tweak to make preview show

* Try some other stuff

* Try documenter secret again

* A tweak

* Tweak

* Tweak

* Improve docs message

* Constain documenter version

* Run doctests as part of regular testing

* Add badge

* Fix spacing in gitignore

.github/workflows/documentation.yml

@@ -0,0 +1,31 @@
+name: Documentation
+
+on:
+ push:
+ branches:
+ - main
+ tags: '*'
+ pull_request:
+
+jobs:
+ build:
+ permissions:
+ contents: write
+ pull-requests: read
+ statuses: write
+ actions: write
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: julia-actions/setup-julia@latest
+ with:
+ version: '1.10'
+ - uses: julia-actions/cache@v1
+ - name: Install dependencies
+ run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+ - name: Build and deploy
+ env:
+ GKSwstype: nul # turn off GR's interactive plotting for notebooks
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+ DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+ run: julia --project=docs/ docs/make.jl

.gitignore

@@ -5,3 +5,6 @@ analysis_results
 .vscode
 profile.pb.gz
 scratch.jl
+docs/build/
+docs/site/
+docs/Manifest.toml

Project.toml

@@ -32,6 +32,7 @@ ChainRulesCore = "1"
 DiffRules = "1"
 DiffTests = "0.1"
 Distributions = "0.25"
+Documenter = "1"
 ExprTools = "0.1"
 FillArrays = "1"
 Graphs = "1"
@@ -50,6 +51,7 @@ AbstractGPs = "99985d1d-32ba-4be9-9821-2ec096f28918"
 BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 DiffTests = "de460e47-3fe3-5279-bb4a-814414816d5d"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 KernelFunctions = "ec8451be-7e33-11e9-00cf-bbf324bd1392"
 LogDensityProblemsAD = "996a588d-648d-4e1f-a8f0-a84b347e47b1"
@@ -62,4 +64,4 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 Turing = "fce5fe82-541a-59a6-adf8-730c64b5f9a0"
 
 [targets]
-test = ["AbstractGPs", "BenchmarkTools", "DiffTests", "Distributions", "FillArrays", "KernelFunctions", "LogDensityProblemsAD", "PDMats", "ReverseDiff", "SpecialFunctions", "StableRNGs", "Test", "Turing", "TemporalGPs"]
+test = ["AbstractGPs", "BenchmarkTools", "DiffTests", "Distributions", "Documenter", "FillArrays", "KernelFunctions", "LogDensityProblemsAD", "PDMats", "ReverseDiff", "SpecialFunctions", "StableRNGs", "Test", "Turing", "TemporalGPs"]

README.md

@@ -3,6 +3,7 @@
 [![Build Status](https://github.com/withbayes/Tapir.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/withbayes/Tapir.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 [![ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://img.shields.io/badge/ColPrac-Contributor's%20Guide-blueviolet)](https://github.com/SciML/ColPrac)
+[![](https://img.shields.io/badge/docs-blue.svg)](https://withbayes.github.io/Tapir.jl/dev)
 
 The goal of the `Tapir.jl` project is to produce a reverse-mode AD package which is written entirely in Julia, which improves over both `ReverseDiff.jl` and `Zygote.jl` in several ways, and is competitive with `Enzyme.jl`.
 

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Tapir = "07d77754-e150-4737-8c94-cd238a1fb45b"
+
+[compat]
+Documenter = "1"

docs/make.jl

@@ -0,0 +1,10 @@
+using Documenter, Tapir
+
+makedocs(
+ sitename="Tapir.jl",
+ format=Documenter.HTML(),
+ modules=[Tapir],
+ checkdocs=:none,
+)
+
+deploydocs(repo="github.com/withbayes/Tapir.jl.git", push_preview=true)

docs/src/index.md

@@ -0,0 +1,3 @@
+# Tapir.jl
+
+Documentation for Tapir.jl is on it's way!

src/Tapir.jl

@@ -44,8 +44,13 @@ The second element contains the pullback, which runs the reverse-pass. It maps f
 the rdata associated to `y` to the rdata associated to `f` and each `x`.
 
 ```jldoctest
+using Tapir: zero_fcodual, CoDual, NoFData, rrule!!
 y, pb!! = rrule!!(zero_fcodual(sin), CoDual(5.0, NoFData()))
 pb!!(1.0)
+
+# output
+
+(Tapir.NoRData(), 0.28366218546322625)
 ```
 """
 function rrule!! end

test/front_matter.jl

@@ -1,6 +1,7 @@
 using
  BenchmarkTools,
  DiffRules,
+ Documenter,
  FillArrays,
  JET,
  LinearAlgebra,

test/runtests.jl

@@ -17,6 +17,7 @@ include("front_matter.jl")
  include(joinpath("interpreter", "zero_like_rdata.jl"))
  include(joinpath("interpreter", "s2s_reverse_mode_ad.jl"))
  end
+ doctest(Tapir)
  elseif test_group == "rrules"
  include("test_utils.jl")
  @testset "rrules" begin