Merge pull request #173 from sathvikbhagavan/sb/fix_docs

Fix example

.github/workflows/CI.yml

@@ -40,35 +40,7 @@ jobs:
             ${{ runner.os }}-
       - uses: julia-actions/julia-buildpkg@72ddd0fcdc760e6d2ef7ef2bbb11ae5032b671a8
       - uses: julia-actions/julia-runtest@79a7e100883947123f8263c5f06e6c0ea3eb972f
-      - name: Test plotting recipes with Weave
-        run: |
-          # Install packages
-          julia --color=yes -e 'using Pkg; Pkg.add(["Weave", "Plots"])'
-          # Process jmd
-          julia --color=yes --code-coverage -e 'using Weave; weave("example/DataInterpolations.jmd")'
       - uses: julia-actions/julia-processcoverage@03114f09f119417c3242a9fb6e0b722676aedf38
       - uses: codecov/codecov-action@eaaf4bedf32dbdc6b720b63067d99c4d77d6047d
         with:
-          file: lcov.info
-#   docs:
-#     name: Documentation
-#     runs-on: ubuntu-latest
-#     steps:
-#       - uses: actions/checkout@8e5e7e5ab8b370d6c329ec480221332ada57f0ab
-#       - uses: julia-actions/setup-julia@f40c4b69330df1d22e7590c12e76dc2f9c66e0bc
-#         with:
-#           version: '1'
-#       - run: |
-#           julia --project=docs -e '
-#             using Pkg
-#             Pkg.develop(PackageSpec(path=pwd()))
-#             Pkg.instantiate()'
-#       - run: |
-#           julia --project=docs -e '
-#             using Documenter: doctest
-#             using MYPACKAGE
-#             doctest(MYPACKAGE)' # change MYPACKAGE to the name of your package
-#       - run: julia --project=docs docs/make.jl
-#         env:
-#           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#           DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+          file: lcov.info

.github/workflows/Documentation.yml

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

.gitignore

@@ -2,3 +2,7 @@
 *.jl.*.cov
 *.jl.mem
 Manifest.toml
+
+# Build artifacts for creating documentation generated by the Documenter package
+docs/build/
+docs/site/

docs/Project.toml

@@ -0,0 +1,7 @@
+[deps]
+DataInterpolations = "82cc6244-b520-54b8-b5a6-8a565e85f1d0"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Optim = "429524aa-4258-5aef-a3af-852621145aeb"
+Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+RegularizationTools = "29dad682-9a27-4bc3-9c72-016788665182"
+StableRNGs = "860ef19b-820b-49d6-a774-d7a799459cd3"

docs/make.jl

@@ -0,0 +1,17 @@
+using Documenter, DataInterpolations
+
+ENV["GKSwstype"] = "100"
+
+makedocs(
+    modules = [DataInterpolations],
+    sitename = "DataInterpolations.jl",
+    warnonly = [:missing_docs],
+    format = Documenter.HTML(),
+    pages = [
+        "index.md",
+        "Methods" => "methods.md",
+        "Interface" => "interface.md"
+    ],
+)
+
+deploydocs(repo = "github.com/PumasAI/DataInterpolations.jl"; push_preview = true)

docs/src/index.md

@@ -0,0 +1,55 @@
+# DataInterpolations.jl
+
+DataInterpolations.jl is a library for performing interpolations of one-dimensional data. By
+"data interpolations" we mean techniques for interpolating possibly noisy data, and thus
+some methods are mixtures of regressions with interpolations (i.e. do not hit the data
+points exactly, smoothing out the lines). This library can be used to fill in intermediate
+data points in applications like timeseries data.
+
+## Available Interpolations
+
+In all cases, `u` an `AbstractVector` of values and `t` is an `AbstractVector` of timepoints
+corresponding to `(u,t)` pairs.
+
+- `ConstantInterpolation(u,t)` - A piecewise constant interpolation.
+
+- `LinearInterpolation(u,t)` - A linear interpolation.
+
+- `QuadraticInterpolation(u,t)` - A quadratic interpolation.
+
+- `LagrangeInterpolation(u,t,n)` - A Lagrange interpolation of order `n`.
+
+- `QuadraticSpline(u,t)` - A quadratic spline interpolation.
+
+- `CubicSpline(u,t)` - A cubic spline interpolation.
+
+- `AkimaInterpolation(u, t)` - Akima spline interpolation provides a smoothing effect and is computationally efficient.
+
+- `BSplineInterpolation(u,t,d,pVec,knotVec)` - An interpolation B-spline. This is a B-spline which hits each of the data points. The argument choices are:
+  	- `d` - degree of B-spline  
+  	- `pVec` - Symbol to Parameters Vector, `pVec = :Uniform` for uniform spaced parameters and `pVec = :ArcLen` for parameters generated by chord length method.  
+  	- `knotVec` - Symbol to Knot Vector, `knotVec = :Uniform` for uniform knot vector, `knotVec = :Average` for average spaced knot vector.
+
+- `BSplineApprox(u,t,d,h,pVec,knotVec)` - A regression B-spline which smooths the fitting curve. The argument choices are the same as the `BSplineInterpolation`, with the additional parameter `h<length(t)` which is the number of control points to use, with smaller `h` indicating more smoothing.
+
+## Extension Methods
+
+The follow methods require extra dependencies and will be loaded as package extensions.
+
+- `Curvefit(u,t,m,p,alg)` - An interpolation which is done by fitting a user-given functional form `m(t,p)` where `p` is the vector of parameters. The user's input `p` is a an initial value for a least-square fitting, `alg` is the algorithm choice to use for optimize the cost function (sum of squared deviations) via `Optim.jl` and optimal `p`s are used in the interpolation. Requires `using RegularizationTools`
+
+## Plotting
+
+DataInterpolations.jl is tied into the Plots.jl ecosystem, by way of RecipesBase.  
+Any interpolation can be plotted using the `plot` command (or any other), since they have type recipes associated with them.
+
+For convenience, and to allow keyword arguments to propagate properly, DataInterpolations.jl also defines several series types, corresponding to different interpolations.
+
+The series types defined are:
+- `:linear_interp`
+- `:quadratic_interp`
+- `:lagrange_interp`
+- `:quadratic_spline`
+- `:cubic_spline`
+
+By and large, these accept the same keywords as their function counterparts.

docs/src/interface.md

@@ -0,0 +1,63 @@
+# Interface for using the Interpolations object
+
+We will again use the same data as the previous tutorial to demonstrate how to use the Interpolations object for computing interpolated values at any time point, its derivatives and integrals.
+
+```@example interface
+using DataInterpolations
+
+# Dependent variable
+u = [14.7, 11.51, 10.41, 14.95, 12.24, 11.22]
+
+# Independent variable
+t = [0.0, 62.25, 109.66, 162.66, 205.8, 252.3]
+```
+
+## Interpolated values
+
+All Interpolation methods return an object from which we can compute the value of the dependent variable at any time point.
+
+We will use `CubicSpline` method for demonstration but the API is same for all the methods.
+
+```@example interface
+A = CubicSpline(u, t)
+
+# For interpolation do, A(t)
+A(100.0) 
+```
+
+!!! note
+    The values computed beyond the range of the time points provided during interpolation will not be reliable as these methods only perform well within the range and the first/last piece polynomial fit is extrapolated on either sides which might not reflect the true nature of the data.
+
+## Derivatives
+
+Derivatives of the interpolated curves can also be computed at any point for all the methods. 
+
+We will continue with the above example, but the API is same for all the methods.
+
+```@example interface
+# derivative(A, t)
+DataInterpolations.derivative(A, 1.0)
+```
+
+## Integrals
+
+Integrals of the interpolated curves can also be computed easily.
+
+Currently, this is implemented only for a few methods - `ConstantInterpolation`, `LinearInterpolation`, `QuadraticInterpolation`, `QuadraticSpline` and `CubicSpline`.
+
+To compute the integrals from the start of time points provided during interpolation to any point, we can do:
+
+```@example interface
+# integral(A, t)
+DataInterpolations.integral(A, 5.0)
+```
+
+If we want to compute integrals between two points, we can do:
+
+```@example interface
+# integral(A, t1, t2)
+DataInterpolations.integral(A, 1.0, 5.0)
+```
+
+!!! note
+    If the times provided in the integral goes beyond the range of the time points provided during interpolation, it uses extrapolation methods to compute the values and hence the integral can be misrepsentative and might not reflect the true nature of the data.