init

.travis.yml

@@ -10,26 +10,7 @@ notifications:
   email: false
 git:
   depth: 99999999
-
-## uncomment the following lines to allow failures on nightly julia
-## (tests will run but not make your overall status red)
-#matrix:
-#  allow_failures:
-#  - julia: nightly
-
-## uncomment and modify the following lines to manually install system packages
-#addons:
-#  apt: # apt-get for linux
-#    packages:
-#    - gfortran
-#before_script: # homebrew for mac
-#  - if [ $TRAVIS_OS_NAME = osx ]; then brew install gcc; fi
-
-## uncomment the following lines to override the default test script
-#script:
-#  - julia -e 'Pkg.clone(pwd()); Pkg.build("DiffResults"); Pkg.test("DiffResults"; coverage=true)'
 after_success:
-  # push coverage results to Coveralls
   - julia -e 'cd(Pkg.dir("DiffResults")); Pkg.add("Coverage"); using Coverage; Coveralls.submit(Coveralls.process_folder())'
-  # push coverage results to Codecov
-  - julia -e 'cd(Pkg.dir("DiffResults")); Pkg.add("Coverage"); using Coverage; Codecov.submit(Codecov.process_folder())'
+  - julia -e 'Pkg.add("Documenter")'
+  - julia -e 'cd(Pkg.dir("DiffResults")); include(joinpath("docs", "make.jl"))'

README.md

@@ -1,7 +1,10 @@
 # DiffResults
 
-[![Build Status](https://travis-ci.org/jrevels/DiffResults.jl.svg?branch=master)](https://travis-ci.org/jrevels/DiffResults.jl)
+Many differentiation techniques can calculate primal values and multiple orders of
+derivatives simultaneously. In other words, there are techniques for computing `f(x)`,
+`∇f(x)` and `H(f(x))` in one fell swoop!
 
-[![Coverage Status](https://coveralls.io/repos/jrevels/DiffResults.jl/badge.svg?branch=master&service=github)](https://coveralls.io/github/jrevels/DiffResults.jl?branch=master)
-
-[![codecov.io](http://codecov.io/github/jrevels/DiffResults.jl/coverage.svg?branch=master)](http://codecov.io/github/jrevels/DiffResults.jl?branch=master)
+For this purpose, DiffResults provides the `DiffResult` type, which can be passed
+to in-place differentiation methods instead of an output buffer. The method
+then loads all computed results into the given `DiffResult`, which the user
+can then query afterwards.

REQUIRE

@@ -1 +1,2 @@
 julia 0.6
+StaticArrays 0.5.0

docs/make.jl

@@ -0,0 +1,14 @@
+using Documenter, DiffResults
+
+makedocs(modules=[DiffResults],
+         doctest = false,
+         format = :html,
+         sitename = "DiffResults",
+         pages = ["Documentation" => "index.md"])
+
+deploydocs(repo = "github.com/JuliaDiff/DiffResults.jl.git",
+           osname = "linux",
+           julia = "0.6",
+           target = "build",
+           deps = nothing,
+           make = nothing)

docs/src/index.md

@@ -0,0 +1,76 @@
+# DiffResults
+
+```@meta
+CurrentModule = DiffResults
+```
+
+Many differentiation techniques can calculate primal values and multiple orders of
+derivatives simultaneously. In other words, there are techniques for computing `f(x)`,
+`∇f(x)` and `H(f(x))` in one fell swoop!
+
+For this purpose, DiffResults provides the `DiffResult` type, which can be passed
+to in-place differentiation methods instead of an output buffer. The method
+then loads all computed results into the given `DiffResult`, which the user
+can then query afterwards.
+
+Here's an example of `DiffResult` in action using ForwardDiff:
+
+```julia
+julia> using ForwardDiff, DiffResults
+
+julia> f(x) = sum(sin, x) + prod(tan, x) * sum(sqrt, x);
+
+julia> x = rand(4);
+
+# construct a `DiffResult` with storage for a Hessian, gradient,
+# and primal value based on the type and shape of `x`.
+julia> result = DiffResults.HessianResult(x)
+
+# Instead of passing an output buffer to `hessian!`, we pass `result`.
+# Note that we re-alias to `result` - this is important! See `hessian!`
+# docs for why we do this.
+julia> result = ForwardDiff.hessian!(result, f, x);
+
+# ...and now we can get all the computed data from `result`
+julia> DiffResults.value(result) == f(x)
+true
+
+julia> DiffResults.gradient(result) == ForwardDiff.gradient(f, x)
+true
+
+julia> DiffResults.hessian(result) == ForwardDiff.hessian(f, x)
+true
+```
+
+The rest of this document describes the API for constructing, accessing, and mutating
+`DiffResult` instances. For details on how to use a `DiffResult` with a specific
+package's methods, please consult that package's documentation.
+
+## Constructing a `DiffResult`
+
+```@docs
+DiffResults.DiffResult
+DiffResults.JacobianResult
+DiffResults.GradientResult
+DiffResults.HessianResult
+```
+
+## Accessing data from a `DiffResult`
+
+```@docs
+DiffResults.value
+DiffResults.derivative
+DiffResults.gradient
+DiffResults.jacobian
+DiffResults.hessian
+```
+
+## Mutating a `DiffResult`
+
+```@docs
+DiffResults.value!
+DiffResults.derivative!
+DiffResults.gradient!
+DiffResults.jacobian!
+DiffResults.hessian!
+```