Setup Documenter

.github/workflows/CI.yml

@@ -0,0 +1,62 @@
+name: CI
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+concurrency:
+  # Skip intermediate builds: always.
+  # Cancel intermediate builds: only if it is a pull request build.
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.6'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+  docs:
+    name: Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: '1'
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}
+      - run: |
+          julia --project=docs -e '
+            using Documenter: DocMeta, doctest
+            using Combinatorics
+            DocMeta.setdocmeta!(Combinatorics, :DocTestSetup, :(using Combinatorics); recursive=true)
+            doctest(Combinatorics)'

README.md

@@ -1,6 +1,7 @@
 # Combinatorics
 
 [![Build Status](https://travis-ci.org/JuliaMath/Combinatorics.jl.svg?branch=master)](https://travis-ci.org/JuliaMath/Combinatorics.jl)
+[![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](http://juliamath.github.io/Combinatorics.jl/)
 [![Coverage Status](https://coveralls.io/repos/github/JuliaMath/Combinatorics.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaMath/Combinatorics.jl?branch=master)
 [![Codecov](https://codecov.io/gh/JuliaMath/Combinatorics.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMath/Combinatorics.jl)
 
@@ -12,41 +13,6 @@ most of the functions always return `BigInt`, and are marked as such below.
 
 In the Julia REPL, type `]add Combinatorics` and then `using Combinatorics` to access the below functions.
 
-## Usage
+## Documentation
 
-This library provides the following functions:
- - `bellnum(n)`: returns the n-th Bell number; always returns a `BigInt`;
- - `catalannum(n)`: returns the n-th Catalan number; always returns a `BigInt`;
- - `lobbnum(m,n)`: returns the generalised Catalan number at `m` and `n`; always returns a `BigInt`;
- - `narayana(n,k)`: returns the general Narayana number at any given `n` and `k`; always returns a `BigInt`;
- - `combinations(a,n)`: returns all combinations of `n` elements of indexable object `a`;
- - `combinations(a)`: returns combinations of all order by chaining calls to `combinations(a,n)`;
- - `derangement(n)`/`subfactorial(n)`: returns the number of permutations of n with no fixed points; always returns a `BigInt`;
- - `partialderangement(n, k)`: returns the number of permutations of n with exactly k fixed points; always returns a `BigInt`;
- - `doublefactorial(n)`: returns the double factorial n!!; always returns a `BigInt`;
- - `fibonaccinum(n)`: the n-th Fibonacci number; always returns a `BigInt`;
- - `hyperfactorial(n)`: the n-th hyperfactorial, i.e. prod([i^i for i = 2:n]; always returns a `BigInt`;
- - `integer_partitions(n)`: returns a `Vector{Int}` consisting of the partitions of the number `n`.
- - `jacobisymbol(a,b)`: returns the Jacobi symbol (a/b);
- - `lassallenum(n)`: returns the nth Lassalle number A<sub>n</sub> defined in [arXiv:1009.4225](http://arxiv.org/abs/1009.4225) ([OEIS A180874](http://oeis.org/A180874)); always returns a `BigInt`;
- - `legendresymbol(a,p)`: returns the Legendre symbol (a/p);
- - `lucasnum(n)`: the n-th Lucas number; always returns a `BigInt`;
- - `multifactorial(n)`: returns the m-multifactorial n(!^m); always returns a `BigInt`;
- - `multinomial(k...)`: receives a tuple of `k_1, ..., k_n` and calculates the multinomial coefficient `(n k)`, where `n = sum(k)`; returns a `BigInt` only if given a `BigInt`;
- - `multiexponents(m,n)`: returns the exponents in the multinomial expansion (x₁ + x₂ + ... + xₘ)ⁿ;
- - `primorial(n)`: returns the product of all positive prime numbers <= n; always returns a `BigInt`;
- - `powerset(a)`: returns all subsets of an indexable object `a`
- - `stirlings1(n, k, signed=false)`: returns the `(n,k)`-th Stirling number of the first kind; the number is signed if `signed` is true; returns a `BigInt` only if given a `BigInt`.
- - `stirlings2(n, k)`: returns the `(n,k)`-th Stirling number of the second kind; returns a `BigInt` only if given a `BigInt`.
- - `nthperm(a, k)`: Compute the `k`th lexicographic permutation of the vector `a`.
- - `permutations(a)`: Generate all permutations of an indexable object `a` in lexicographic order.
-
-Young diagrams
---------------
-Limited support for working with Young diagrams is provided.
-
-- `partitionsequence(a)`: computes partition sequence for an integer partition `a`
-- `x = a \ b` creates the skew diagram for partitions (tuples) `a`, `b`
-- `isrimhook(x)`: checks if skew diagram `x` is a rim hook
-- `leglength(x)`: computes leg length of rim hook `x`
-- `character(a, b)`: computes character the partition `b` in the `a`th irrep of Sn
+Go to http://juliamath.github.io/Combinatorics.jl/ to see the list of exported functions and their meanings.

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Combinatorics = "861a8166-3701-5b0c-9a16-15d98fcdc6aa"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"

docs/make.jl

@@ -0,0 +1,18 @@
+using Documenter
+using Combinatorics
+
+DocMeta.setdocmeta!(Combinatorics, :DocTestSetup, :(using Combinatorics); recursive=true)
+
+makedocs(
+    sitename="Combinatorics.jl",
+    repo="github.com/JuliaMath/Combinatorics.jl/",
+    format = Documenter.HTML(
+        prettyurls = get(ENV, "CI", nothing) == "true"
+    ),
+    pages = ["index.md", "api.md"]
+)
+
+deploydocs(;
+    repo="github.com/JuliaMath/Combinatorics.jl",
+    devbranch="master",
+)

docs/src/README_old.md

@@ -0,0 +1,52 @@
+# Combinatorics
+
+[![Build Status](https://travis-ci.org/JuliaMath/Combinatorics.jl.svg?branch=master)](https://travis-ci.org/JuliaMath/Combinatorics.jl)
+[![Coverage Status](https://coveralls.io/repos/github/JuliaMath/Combinatorics.jl/badge.svg?branch=master)](https://coveralls.io/github/JuliaMath/Combinatorics.jl?branch=master)
+[![Codecov](https://codecov.io/gh/JuliaMath/Combinatorics.jl/branch/master/graph/badge.svg)](https://codecov.io/gh/JuliaMath/Combinatorics.jl)
+
+A combinatorics library for Julia, focusing mostly (as of now) on enumerative
+combinatorics and permutations.  As overflows are expected even for low values,
+most of the functions always return `BigInt`, and are marked as such below.
+
+## Installation
+
+In the Julia REPL, type `]add Combinatorics` and then `using Combinatorics` to access the below functions.
+
+## Usage
+
+This library provides the following functions:
+ - `bellnum(n)`: returns the n-th Bell number; always returns a `BigInt`;
+ - `catalannum(n)`: returns the n-th Catalan number; always returns a `BigInt`;
+ - `lobbnum(m,n)`: returns the generalised Catalan number at `m` and `n`; always returns a `BigInt`;
+ - `narayana(n,k)`: returns the general Narayana number at any given `n` and `k`; always returns a `BigInt`;
+ - `combinations(a,n)`: returns all combinations of `n` elements of indexable object `a`;
+ - `combinations(a)`: returns combinations of all order by chaining calls to `combinations(a,n)`;
+ - `derangement(n)`/`subfactorial(n)`: returns the number of permutations of n with no fixed points; always returns a `BigInt`;
+ - `partialderangement(n, k)`: returns the number of permutations of n with exactly k fixed points; always returns a `BigInt`;
+ - `doublefactorial(n)`: returns the double factorial n!!; always returns a `BigInt`;
+ - `fibonaccinum(n)`: the n-th Fibonacci number; always returns a `BigInt`;
+ - `hyperfactorial(n)`: the n-th hyperfactorial, i.e. prod([i^i for i = 2:n]; always returns a `BigInt`;
+ - `integer_partitions(n)`: returns a `Vector{Int}` consisting of the partitions of the number `n`.
+ - `jacobisymbol(a,b)`: returns the Jacobi symbol (a/b);
+ - `lassallenum(n)`: returns the nth Lassalle number A<sub>n</sub> defined in [arXiv:1009.4225](http://arxiv.org/abs/1009.4225) ([OEIS A180874](http://oeis.org/A180874)); always returns a `BigInt`;
+ - `legendresymbol(a,p)`: returns the Legendre symbol (a/p);
+ - `lucasnum(n)`: the n-th Lucas number; always returns a `BigInt`;
+ - `multifactorial(n)`: returns the m-multifactorial n(!^m); always returns a `BigInt`;
+ - `multinomial(k...)`: receives a tuple of `k_1, ..., k_n` and calculates the multinomial coefficient `(n k)`, where `n = sum(k)`; returns a `BigInt` only if given a `BigInt`;
+ - `multiexponents(m,n)`: returns the exponents in the multinomial expansion (x₁ + x₂ + ... + xₘ)ⁿ;
+ - `primorial(n)`: returns the product of all positive prime numbers <= n; always returns a `BigInt`;
+ - `powerset(a)`: returns all subsets of an indexable object `a`
+ - `stirlings1(n, k, signed=false)`: returns the `(n,k)`-th Stirling number of the first kind; the number is signed if `signed` is true; returns a `BigInt` only if given a `BigInt`.
+ - `stirlings2(n, k)`: returns the `(n,k)`-th Stirling number of the second kind; returns a `BigInt` only if given a `BigInt`.
+ - `nthperm(a, k)`: Compute the `k`th lexicographic permutation of the vector `a`.
+ - `permutations(a)`: Generate all permutations of an indexable object `a` in lexicographic order.
+
+Young diagrams
+--------------
+Limited support for working with Young diagrams is provided.
+
+- `partitionsequence(a)`: computes partition sequence for an integer partition `a`
+- `x = a \ b` creates the skew diagram for partitions (tuples) `a`, `b`
+- `isrimhook(x)`: checks if skew diagram `x` is a rim hook
+- `leglength(x)`: computes leg length of rim hook `x`
+- `character(a, b)`: computes character the partition `b` in the `a`th irrep of Sn

docs/src/api.md

@@ -0,0 +1,50 @@
+# API reference
+
+## Combinations
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["combinations.jl"]
+```
+
+## Factorials
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["factorials.jl"]
+```
+
+## Multinomials
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["multinomials.jl"]
+```
+
+## Numbers
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["numbers.jl"]
+```
+
+## Partitions
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["partitions.jl"]
+```
+
+## Permutations
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["permutations.jl"]
+```
+
+## Young diagrams
+
+```@autodocs
+Modules = [Combinatorics]
+Pages   = ["youngdiagrams.jl"]
+```

docs/src/index.md

@@ -0,0 +1,12 @@
+# Getting started
+
+A combinatorics library for Julia, focusing mostly (as of now) on enumerative combinatorics and permutations. As overflows are expected even for low values, most of the functions always return BigInt, and are marked as such below.
+
+## Installation
+
+In the Julia REPL, type `]add Combinatorics` and then `using Combinatorics` to access the functions listed below.
+
+## Index
+
+```@index
+```