Merge pull request #5 from SciML/docs

Build a basic docs

.github/workflows/Documentation.yml

@@ -0,0 +1,30 @@
+name: Documentation
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+  schedule:
+    - cron: '47 20 * * 0'
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+      - 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
+      - uses: julia-actions/julia-processcoverage@v1
+        with:
+          directories: src
+      - uses: codecov/codecov-action@v3
+        with:
+          files: lcov.info

Project.toml

@@ -1,7 +1,7 @@
 name = "FindFirstFunctions"
 uuid = "64ca27bc-2ba2-4a57-88aa-44e436879224"
 authors = ["Chris Elrod <[email protected]> and contributors"]
-version = "1.1.0"
+version = "1.2.0"
 
 [compat]
 julia = "1.8"

README.md

@@ -41,7 +41,7 @@ See `sort!` for an explanation of the keyword arguments `by`, `lt` and `rev`.
 ### `searchsortedfirstcorrelated(v::AbstractVector, x, guess)`
 
 ```julia
-searchsortedfirstcorrelated(v::AbstractVector, x, guess)
+searchsortedfirstcorrelated(v::AbstractVector{T}, x, guess::T)
 ```
 
 An accelerated `findfirst` on sorted vectors using a bracketed search. Requires a `guess`

docs/Project.toml

@@ -0,0 +1,15 @@
+[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"
+
+[compat]
+DataInterpolations = "4"
+Documenter = "1"
+Optim = "1"
+Plots = "1"
+RegularizationTools = "0.6"
+StableRNGs = "1"

docs/make.jl

@@ -0,0 +1,18 @@
+using Documenter, FindFirstFunctions
+
+cp("./docs/Manifest.toml", "./docs/src/assets/Manifest.toml", force = true)
+cp("./docs/Project.toml", "./docs/src/assets/Project.toml", force = true)
+
+ENV["GKSwstype"] = "100"
+
+makedocs(modules = [FindFirstFunctions],
+    sitename = "FindFirstFunctions.jl",
+    clean = true,
+    doctest = false,
+    linkcheck = true,
+    warnonly = [:missing_docs],
+    format = Documenter.HTML(assets = ["assets/favicon.ico"],
+        canonical = "https://docs.sciml.ai/FindFirstFunctions/stable/"),
+    pages = ["index.md"])
+
+deploydocs(repo = "github.com/SciML/FindFirstFunctions.jl"; push_preview = true)

docs/src/index.md

@@ -0,0 +1,94 @@
+# FindFirstFunctions.jl
+
+FindFirstFunctions.jl is a library for accelerated `findfirst` type functions.
+
+## Installation
+
+To install FindFirstFunctions.jl, use the Julia package manager:
+
+```julia
+using Pkg
+Pkg.add("FindFirstFunctions")
+```
+
+## Available Functions
+
+```@docs
+FindFirstFunctions.findfirstequal
+FindFirstFunctions.bracketstrictlymontonic
+FindFirstFunctions.searchsortedfirstcorrelated
+```
+
+## Contributing
+
+  - Please refer to the
+    [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md)
+    for guidance on PRs, issues, and other matters relating to contributing to SciML.
+
+  - See the [SciML Style Guide](https://github.com/SciML/SciMLStyle) for common coding practices and other style decisions.
+  - There are a few community forums:
+
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Slack](https://julialang.org/slack/)
+      + The #diffeq-bridged and #sciml-bridged channels in the
+        [Julia Zulip](https://julialang.zulipchat.com/#narrow/stream/279055-sciml-bridged)
+      + On the [Julia Discourse forums](https://discourse.julialang.org)
+      + See also [SciML Community page](https://sciml.ai/community/)
+
+## Reproducibility
+
+```@raw html
+<details><summary>The documentation of this SciML package was built using these direct dependencies,</summary>
+```
+
+```@example
+using Pkg # hide
+Pkg.status() # hide
+```
+
+```@raw html
+</details>
+```
+
+```@raw html
+<details><summary>and using this machine and Julia version.</summary>
+```
+
+```@example
+using InteractiveUtils # hide
+versioninfo() # hide
+```
+
+```@raw html
+</details>
+```
+
+```@raw html
+<details><summary>A more complete overview of all dependencies and their versions is also provided.</summary>
+```
+
+```@example
+using Pkg # hide
+Pkg.status(; mode = PKGMODE_MANIFEST) # hide
+```
+
+```@raw html
+</details>
+```
+
+```@eval
+using TOML
+using Markdown
+version = TOML.parse(read("../../Project.toml", String))["version"]
+name = TOML.parse(read("../../Project.toml", String))["name"]
+link_manifest = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+                "/assets/Manifest.toml"
+link_project = "https://github.com/SciML/" * name * ".jl/tree/gh-pages/v" * version *
+               "/assets/Project.toml"
+Markdown.parse("""You can also download the
+[manifest]($link_manifest)
+file and the
+[project]($link_project)
+file.
+""")
+```

src/FindFirstFunctions.jl

@@ -1,5 +1,10 @@
 module FindFirstFunctions
 
+"""
+    findfirstequal(x::Int64,A::DenseVector{Int64})
+
+Finds the first value in `A` equal to `x`
+"""
 findfirstequal(vpivot, ivars) = findfirst(isequal(vpivot), ivars)
 function findfirstequal(vpivot::Int64, ivars::DenseVector{Int64})
   GC.@preserve ivars begin
@@ -86,7 +91,7 @@ purpose of using this function first would be to accelerate convergence in those
 by using correlated `guess`es for repeated calls.  The best `guess` for the next call of
 this function would be the index returned by the previous call to `searchsorted`.
 
-See [`sort!`](@ref) for an explanation of the keyword arguments `by`, `lt` and `rev`.
+See `Base.sort!` for an explanation of the keyword arguments `by`, `lt` and `rev`.
 """
 function bracketstrictlymontonic(v::AbstractVector,
         x,
@@ -121,6 +126,12 @@ function bracketstrictlymontonic(v::AbstractVector,
     return lo, hi
 end
 
+"""
+    searchsortedfirstcorrelated(v::AbstractVector{T}, x, guess)
+
+An accelerated `findfirst` on sorted vectors using a bracketed search. Requires a `guess::T`
+to start the search from.
+"""
 function searchsortedfirstcorrelated(v::AbstractVector, x, guess)
     lo, hi = bracketstrictlymontonic(v, x, guess, Base.Order.Forward)
     searchsortedfirst(v, x, lo, hi, Base.Order.Forward)