Merge pull request #28 from SciML/gd/documenter

Add docs website and revamp README

.github/workflows/Documentation.yml

@@ -0,0 +1,28 @@
+name: Documentation
+
+on:
+ push:
+ branches:
+ - main
+ tags: '*'
+ pull_request:
+
+jobs:
+ build:
+ permissions:
+ contents: write
+ statuses: write
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: julia-actions/setup-julia@v1
+ with:
+ version: '1'
+ - 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:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
+ DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
+ run: julia --project=docs/ docs/make.jl

.gitignore

@@ -1 +1,2 @@
-/Manifest.toml
+Manifest.toml
+/docs/build/

README.md

@@ -1,56 +1,32 @@
 # ADTypes.jl: Multi-Valued Logic for Automatic Differentiation Choices
 
-[![Build Status](https://github.com/Vaibhavdixit02/ADTypes.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/Vaibhavdixit02/ADTypes.jl/actions/workflows/CI.yml?query=branch%3Amain)
-
-ADTypes.jl is a common system for implementing multi-valued logic for choosing which
-automatic differentiation library to use.
-
-## Which libraries are supported?
-
-Just run the following code in a Julia REPL to find out:
-
-```julia
-julia> using ADTypes
-
-julia> names(ADTypes)
-16-element Vector{Symbol}:
- :ADTypes
- :AutoChainRules
- :AutoEnzyme
- :AutoFiniteDiff
- :AutoFiniteDifferences
- :AutoForwardDiff
- :AutoModelingToolkit
- :AutoPolyesterForwardDiff
- :AutoReverseDiff
- :AutoSparseFiniteDiff
- :AutoSparseForwardDiff
- :AutoSparsePolyesterForwardDiff
- :AutoSparseReverseDiff
- :AutoSparseZygote
- :AutoTracker
- :AutoZygote
-```
-
-Use the help mode of the Julia REPL to find out more about a specific library.
-
-## Why Should Packages Adopt This?
-
-The current standard is to have a keyword argument with `autodiff = true` or `autodiff = false`.
-However, boolean logic is not sufficient to be able to do all of the choices that are
-required. For example for forward-mode AD there is ForwardDiff vs Enzyme, and thus `true`
-is ambgiuous. As libraries begin to support more and more of these autodiff mechanisms
-for their trade-offs, every library will have their own version of `ChooseForwardDiff()`
-etc. which would be a mess. Hence ADTypes.jl giving a single set of shared types for this.
-`ADTypes.AutoForwardDiff()` is the way to do it.
-
-## Why are they types instead of enums? Or EnumX?
-
-If they were enums then they would not be dispatch type-level information. This is needed
-for the internals of many of the packages to be type-stable because the choice of `config`
-type is different per package, i.e. what needs to be cached in order to use everything in
-a non-allocating manner.
-
-## My AD Package is Missing?
-
-Sure, give a PR to add it.
+[![Docs stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://SciML.github.io/ADTypes.jl/stable/)
+[![Docs dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://SciML.github.io/ADTypes.jl/dev/)
+[![Build Status](https://github.com/SciML/ADTypes.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/SciML/ADTypes.jl/actions/workflows/CI.yml?query=branch%3Amain)
+
+ADTypes.jl is a multi-valued logic system specifying the choice of an automatic differentiation (AD) library and its parameters.
+
+## Which AD libraries are supported?
+
+See the API reference in the documentation.
+
+## Why should packages adopt this standard?
+
+A common practice is the use of a boolean keyword argument like `autodiff = true/false`.
+However, boolean logic is not precise enough for all the choices required.
+For instance, forward mode AD is implemented by both ForwardDiff and Enzyme, which makes `autodiff = true` ambiguous.
+Something like `ChooseForwardDiff()` is thus required, possibly with additional parameters depending on the library.
+
+The risk is that every package developer might develop their own version of `ChooseForwardDiff()`, which would ruin interoperability.
+This is why ADTypes.jl provides a single set of shared types for this task, as an extremely lightweight dependency.
+Wonder no more: `ADTypes.AutoForwardDiff()` is the way to go.
+
+## Why define types instead of enums?
+
+If we used enums, they would not contain type-level information useful for dispatch.
+This is needed by many AD libraries to ensure type stability.
+Notably, the choice of config or cache type is different with each AD, so we must know statically which AD library is chosen.
+
+## Why is this AD package missing?
+
+Feel free to open a pull request adding it.

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+ADTypes = "47edcb42-4c32-4615-8424-f2b9edc5f35b"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "1.3"

docs/make.jl

@@ -0,0 +1,12 @@
+using Documenter
+using ADTypes
+
+makedocs(
+ sitename = "ADTypes",
+ format = Documenter.HTML(),
+ modules = [ADTypes]
+)
+
+deploydocs(
+ repo = "https://github.com/SciML/ADTypes.jl.git"
+)

docs/src/index.md

@@ -0,0 +1,22 @@
+```@meta
+CurrentModule = ADTypes
+CollapsedDocStrings = true
+```
+
+# ADTypes.jl
+
+Documentation for [ADTypes.jl](https://github.com/SciML/ADTypes.jl/).
+
+## Public
+
+```@autodocs
+Modules = [ADTypes]
+Private = false
+```
+
+## Internal
+
+```@autodocs
+Modules = [ADTypes]
+Public = false
+```