Add a documentation page (#69)

* init docs page

* fill more details

* add contributing details

* add Documenter dependency

* fix compat

* fix compat

* add more doc strings

* fix escape

* fix escape

* add hankel docs

* add airy and spherical docs

* fix parse and add doc badge

* fix parse

Author: heltonmc

.github/workflows/documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master # update to match your development branch (master, main, dev, trunk, ...)
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1.6'
+      - 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

README.md

@@ -1,5 +1,6 @@
 # Bessels.jl
 [![Build Status](https://github.com/heltonmc/Bessels.jl/actions/workflows/CI.yml/badge.svg?branch=master)](https://github.com/heltonmc/Bessels.jl/actions/workflows/CI.yml?query=branch%3Amaster)
+[![Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://juliamath.github.io/Bessels.jl/stable)
 [![Coverage](https://codecov.io/gh/heltonmc/Bessels.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/heltonmc/Bessels.jl)
 
 [![version](https://juliahub.com/docs/Bessels/version.svg)](https://juliahub.com/ui/Packages/Bessels/29L49)

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+Bessels = "0e736298-9ec6-45e8-9647-e4fc86a2fe38"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "~0.24"

docs/make.jl

@@ -0,0 +1,19 @@
+push!(LOAD_PATH,"../src/")
+using Documenter, Bessels
+
+makedocs(
+         sitename = "Bessels.jl",
+         modules  = [Bessels],
+         pages=[
+                "Home" => "index.md",
+                "Getting started" => "install.md",
+                "Roadmap" => "roadmap.md",
+                "Contributing" => "contribute.md",
+                "API" => "API.md",
+                "Function list" => "functions.md",
+               ]
+)
+               
+deploydocs(
+    repo="github.com/JuliaMath/Bessels.jl.git",
+)

docs/src/API.md

@@ -0,0 +1,60 @@
+## Bessel functions
+
+```@docs
+besselj
+Bessels.besselj!
+besselj0
+besselj1
+bessely
+Bessels.bessely!
+bessely0
+bessely1
+Bessels.besseljy
+```
+
+## Modified Bessel functions
+
+```@docs
+besseli
+Bessels.besseli!
+besseli0
+besseli0x
+besseli1
+besseli1x
+besselix
+besselk
+Bessels.besselk!
+besselk0
+besselk0x
+besselk1
+besselk1x
+besselkx
+```
+
+## Hankel functions
+```@docs
+besselh
+hankelh1
+hankelh2
+```
+
+## Spherical Bessel functions
+```@docs
+sphericalbesselj
+sphericalbessely
+Bessels.sphericalbesseli
+Bessels.sphericalbesselk
+```
+
+# Airy functions
+```@docs
+airyai
+airyaiprime
+airybi
+airybiprime
+```
+
+# Gamma functions
+```@docs
+Bessels.gamma
+```

docs/src/contribute.md

@@ -0,0 +1,30 @@
+## Contributors Guide
+
+Contributions of any kind are very welcome! Bessels.jl is a community-driven project and is under the JuliaMath organization.
+If you are interested in getting involved with the development of Bessels.jl please feel free to open an issue. In general, contributions will likely fall under four main categories:
+
+**1. Implementing a new function**
+
+Any Bessel type or related function is welcome for inclusion in this library. Please read the scope section for more details but in general any function listed [here](https://mpmath.org/doc/current/functions/bessel.html) would be a good addition. Opening an issue would be a great start to further discuss a particular function or implementation details. If you already have an existing function ready to go please open a pull request. Porting functions from MIT compatible implementation is also acceptable.
+
+In general, Bessels.jl aims to provide highly accurate implementations. We do not have a set error tolerance we are willing to accept as it will depend on the function. For example, the `gamma` function is a very important and widely used function so it is necessary to provide maximal errors less than 2 Units in the last place (ULP). For other functions, such as the Bessel function, which oscillate around zero it is much more difficult to provide such tight error tolerances. Therefore, relative tolerances better than `1e-14` would be a good target with a slightly less tolerance around the zeros. Single variable functions should be able to provide better tolerances than multi-variable functions.
+
+Even if the function isn't quite to those error tolerances, please open a pull request to discuss further. It might be good for a single precision implementation or there might be opportunities to improve the errors of the existing implementation. Though, there are fairly strict criteria that the function should be non-allocating and type stable.
+
+**2. Improving exisiting function**
+
+Improving the accuracy or speed of any implementation would be a great contribution. There are plenty of opportunities so please open an issue if you are interested and we can point you to a good function to work with. Accuracy improvements are always welcome whereas any speed improvements would also need to maintain the current level of accuracy. Ideally, implementations could trend to more accurate and faster but there will always be some tradeoff.
+
+**3. Filing bug reports, writing tests, feature requests, improve documentation**
+
+Testing the accuracy and performance of each function is also welcome. In the future, we hope to have an automated way to print out the error and performance of each function so any help with this would be appreciated. Additionally, contributing better tests and writing documentation is very helpful. Filing feature requests are also very helpful.
+
+**4. Other miscellaneous contributions**
+
+Please also share any papers or discussions on implementation details!
+
+#### Pull Requests
+
+Contributions should be made via pull requests on GitHub. This can be done by forking Bessels.jl and making commits on your own fork. After you have made all necessary changes please submit a pull request against the main branch. We will then review and provide any feedback on the changes. Once you a submit a PR, the automated tests will run through CI. Therefore, please also include tests if you are implementing a new function and review the results of the CI run. We typically keep all tests passing on the main branch, so any CI failures are most likely related to the PR. By submitting a pull request, you are agreeing for contributed code to be under the MIT license.
+
+**Code Style:** There is not an explicit code style that we use. Please try to keep it as consistent as possible with existing code.

docs/src/functions.md

@@ -0,0 +1,3 @@
+```@index
+Pages   = ["API.md"]
+```

docs/src/index.md

@@ -0,0 +1,67 @@
+# Bessels.jl
+
+## Introduction
+
+Bessels.jl is a collection of mathematical algorithms to compute special functions written entirely in the Julia programming language. It is focused on providing high quality implementations of mathematical functions that are accurate and highly performant. Since it contains only Julia code and has no external dependencies, it is a lightweight package that can be used in any high performance application while taking advatnage of the dynamism of the Julia language.
+
+Bessels.jl contains numerous definitions of special functions important in many fields of mathematical physics. Available functions include Bessel, Modified Bessel, Spherical Bessel, Airy, Hankel, and Gamma functions. A full list of availabe functions can be found in the API section of this documentation. Initial development has focused on providing implementations for real arguments, however, some functions (e.g., Airy) also accept complex numbers as input.
+
+## Scope
+
+Bessels.jl started simply as a package to compute just the Bessel function of the first kind and zero order, but it has quickly grown to include several Bessel type functions. As mentioned earlier, Bessels.jl contains algorithms for computing Bessel, Modified Bessel, Spherical Bessel, Airy, and Hankel functions. These functions are contained in Chapters 9 and 10 of the [NIST Digitial Library of Mathematical Functions](https://dlmf.nist.gov/). However, there exists other types of related functions such as the Struve and Weber type functions contained in Chapters 11 and 12. In general, these are special cases of the confuent hypergeometric functions $_0F_1, _1F_1$, and $_1F_2$. Additionally, several other special functions such as the gamma functions are also needed to compute these types of functions.
+
+Therefore, Bessels.jl seeks to be home to any Bessel or related functions (see the section provided by [mpmath](https://mpmath.org/doc/current/functions/bessel.html)) which are typically contained in Chapters 9-12 of the NIST Digital library or to any other related function required to compute Bessel type functions.
+
+### Advantages
+
+- Typically 2-12x faster than other available [implementations](https://github.com/JuliaMath/SpecialFunctions.jl)
+- Written entirely in Julia
+
+### Limitations
+
+- Does not yet support automatic differentiation
+- Limited support for complex arguments
+- No support for higher precision (above `Float64`)
+
+## Packages using Bessels.jl
+
+- [Meshes.jl](https://github.com/JuliaGeometry/Meshes.jl)
+- [GeoStats.jl](https://github.com/JuliaEarth/GeoStats.jl)
+- [BesselK.jl](https://github.com/cgeoga/BesselK.jl)
+- [SparseIR.jl](https://github.com/SpM-lab/SparseIR.jl)
+- [Variography.jl](https://github.com/JuliaEarth/Variography.jl)
+- [LightPropagation.jl](https://github.com/heltonmc/LightPropagation.jl)
+
+If you are using Bessels.jl, please feel free to add yours to the list!
+
+## Related Math libraries
+
+**Julia packages**
+- [SpecialFunctions.jl](https://github.com/JuliaMath/SpecialFunctions.jl)
+- [HypergeometricFunctions.jl](https://github.com/JuliaMath/HypergeometricFunctions.jl)
+- [ClassicalOrthogonalPolynomials.jl](https://github.com/JuliaApproximation/ClassicalOrthogonalPolynomials.jl)
+- [LegendrePolynomials.jl](https://github.com/jishnub/LegendrePolynomials.jl)
+- [BesselK.jl](https://github.com/cgeoga/BesselK.jl)
+- [AssociatedLegendrePolynomials.jl](https://github.com/jmert/AssociatedLegendrePolynomials.jl)
+- [HarmonicOrthogonalPolynomials.jl](https://github.com/JuliaApproximation/HarmonicOrthogonalPolynomials.jl)
+- [SphericalHarmonics.jl](https://github.com/jishnub/SphericalHarmonics.jl)
+- [ArbNumerics.jl](https://github.com/JeffreySarnoff/ArbNumerics.jl)
+- [Elliptic.jl](https://github.com/nolta/Elliptic.jl)
+- [EllipticFunctions.jl](https://github.com/stla/EllipticFunctions.jl)
+- [ClausenFunctions.jl](https://github.com/Expander/ClausenFunctions.jl)
+- [Polylogarithms.jl](https://github.com/mroughan/Polylogarithms.jl)
+- [PolyLog.jl](https://github.com/Expander/PolyLog.jl)
+- [LambertW.jl](https://github.com/jlapeyre/LambertW.jl)
+- [Struve.jl](https://github.com/gwater/Struve.jl)
+- [Quadmath.jl](https://github.com/JuliaMath/Quadmath.jl)
+
+**Other**
+- [SciPy](https://github.com/scipy/scipy)
+- [mpmath](https://github.com/mpmath/mpmath)
+- [Arb](https://github.com/fredrik-johansson/arb)
+- [Boost](https://github.com/boostorg/boost)
+- [GSL](https://www.gnu.org/software/gsl/)
+- [Cephes](https://netlib.org/cephes/)
+- [fortran-bessels](https://github.com/perazz/fortran-bessels)
+
+This is by no means exhaustive so please add yours or any others that should be listed.

docs/src/install.md

@@ -0,0 +1,46 @@
+### Installation requirements
+
+Bessels requires Julia v1.6 or later but it is recommended to use the latest stable release. Bessels uses CI tools provided by GitHub Actions to run tests on Julia versions 1.6, current stable release, and nightly builds on Linux operating systems using `ubuntu-latest`. Though, Bessels is written entirely in Julia and therefore should work on any of the [supported platforms](https://julialang.org/downloads/#supported_platforms) such as MacOS and Windows.
+
+### Installation
+
+Install Julia by [downloading](https://julialang.org/downloads/) the latest version from the offical site and follow the [platform specific installations](https://julialang.org/downloads/platform/). 
+
+You can add Bessels using Julia's package manager by typing `] add Bessels` in the Julia prompt.
+
+```julia
+julia> ] # ']' should be pressed
+
+(@v1.8) pkg> add Bessels
+```
+
+The package manager can also be used verify the installation by running the bundled tests, check the installed version, or update to the latest release.
+
+```julia
+julia> ]
+
+# run tests
+(@v1.8) pkg> test Bessels
+
+# check version
+(@v1.8) pkg> status Bessels
+Status `~/.julia/environments/v1.8/Project.toml`
+  [0e736298] Bessels v0.2.7
+
+# update to latest release
+(@v1.8) pkg> update Bessels
+```
+
+### Running
+
+At this point you are ready to start using Bessels.jl!
+
+```julia
+julia> using Bessels
+
+julia> besselj0(1.2)
+0.6711327442643626
+
+julia> besselj(1.8, 10.1)
+0.2374319718222891
+```

docs/src/roadmap.md

@@ -0,0 +1,23 @@
+## Bessels.jl Roadmap
+
+The major development goals can be summarized by the following groups.
+
+### Support for complex arguments
+
+The current development and immediate goals of this project is to provide support for complex variables in all the existing functions. Currently, the Airy functions `airyai`, `airyaiprime`, `airybi`, and `airybiprime` are the only supported functions using complex variables. This will be implemented in a step approach focusing on single argument functions with fixed order (e.g. $\nu=0, 1$) then expanded to the general case of arbitrary order. Therefore, current focus is on developing complex routines for `besselj0(z)`, `besselj1(z)`, `bessely0(z)`, `bessely1(z)`, `besselk0(z)`, `besselk1(z)`, `besseli0(z)`, and `besseli1(z)`.
+
+### Adding additional special functions
+
+A nice list of Bessel and related functions is provided by [mpmath](https://mpmath.org/doc/current/functions/bessel.html). Any function listed there would be a good candidate for inclusion in this package. Functions on the current scope are the Kelvin, Struve, and Scorer type functions. If other functions (or the ones listed) are desired, please open an issue!
+
+### Develop higher precision routines
+
+Current development has focused on single and double precison routine (`Float32` and `Float64`). We intend to also provide support for higher precision types such as double-double (`Double64`) and/or quadruple  (`Float128`) precision in the future. 
+
+### Derivatives through automatic differentiation
+
+Typically, the derivatives of certain special functions with respect to argument can be obtained through definitions. However, derivative with respect to the order usually does not have a simple expression. Automatic differentiation could be a powerful tool to quickly compute higher order derivatives using native Julia code. This is not an immediate goal but would be a welcome contribution.
+
+### Accuracy and Peformance improvements
+
+Speed improvements are beneficial in most cases as these low level functions are typically called many times. Performance gains can come from using better algorithms or through better support for parallelization (e.g., vectorization, SIMD). In general, any speed improvements will only be incoporated that maintain the current relative accuracy. Accuracy improvements may come at the cost of a slightly longer runtime. These type of improvements will come on a more ad-hoc basis.