Skip to content

Commit a6b54d9

Browse files
0x0f0f0f0x0f0f0f
authored
Merge pull request #42 from JuliaSymbolics/ale/makedocs
Add real docs
2 parents bbfd353 + 674928b commit a6b54d9

File tree

7 files changed

+109
-120
lines changed

7 files changed

+109
-120
lines changed

‎.github/workflows/docs.yml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
name: Docs
2+
on:
3+
pull_request:
4+
branches:
5+
- master
6+
push:
7+
branches:
8+
- master
9+
tags: "*"
10+
jobs:
11+
docs:
12+
name: Documentation
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v4
16+
- uses: julia-actions/julia-buildpkg@latest
17+
- uses: julia-actions/julia-docdeploy@latest
18+
env:
19+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
20+
DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }}

‎Project.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
name = "TermInterface"
22
uuid = "8ea1fca8-c5ef-4a55-8b96-4e9afe9c9a3c"
33
authors = ["Shashi Gowda <gowda@mit.edu>", "Alessandro Cheli <sudo-woodo3@protonmail.com>"]
4-
version = "1.0.0"
4+
version = "1.0.1"
55

66
[compat]
77
julia = "1"

‎README.md

Lines changed: 1 addition & 119 deletions
Original file line numberDiff line numberDiff line change
@@ -5,123 +5,5 @@ Its purpose is to provide a shared interface between various symbolic programmin
55
[SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl), [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) and [Metatheory.jl](https://github.com/0x0f0f0f/Metatheory.jl).
66

77
## Docs
8-
You should define the following methods for an expression tree type `T` with symbol types `S` to work
9-
with TermInterface.jl, and therefore with [SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl)
10-
and [Metatheory.jl](https://github.com/0x0f0f0f/Metatheory.jl).
118

12-
#### `isexpr(x::T)`
13-
14-
Returns `true` if `x` is an expression tree. If true, `head(x)` and `children(x)` methods must be defined for `x`.
15-
Optionally, if `x` represents a function call, `iscall(x)` should be true, and `operation(x)` and `arguments(x)` should also be defined.
16-
17-
#### `iscall(x::T)`
18-
19-
Returns `true` if `x` is a function call expression. If true, `operation(x)`, `arguments(x)`
20-
must also be defined for `x`.
21-
22-
If `iscall(x)` is true, then also `isexpr(x)` *must* be true. The other way around is not true.
23-
(A function call is always an expression node, but not every expression tree represents a function call).
24-
25-
This means that, `head(x)` and `children(x)` must be defined. Together
26-
with `operation(x)` and `arguments(x)`.
27-
28-
**Examples:**
29-
30-
In a functional language, all expression trees are function calls (e.g. SymbolicUtils.jl).
31-
Let's say that you have an hybrid array and functional language. `iscall` on the expression `v[i]`
32-
is `false`, and `iscall` on expression `f(x)` is `true`, but both of them are nested
33-
expressions, and `isexpr` is `true` on both.
34-
35-
The same goes for Julia `Expr`. An `Expr(:block, ...)` is *not a function call*
36-
and has no `operation` and `arguments`, but has a `head` and `children`.
37-
38-
39-
The distinction between `head`/`children` and `operation`/`arguments` is needed
40-
when dealing with languages that are *not representing function call operations as their head*.
41-
The main example is `Expr(:call, :f, :x)`: it has both a `head` and an `operation`, which are
42-
respectively `:call` and `:f`.
43-
44-
In other symbolic expression languages, such as SymbolicUtils.jl, the `head` of a node
45-
can correspond to `operation` and `children` can correspond to `arguments`.
46-
47-
#### `head(x)`
48-
49-
Returns the head of the S-expression.
50-
51-
#### `children(x)`
52-
53-
Returns the children (aka tail) of the S-expression.
54-
55-
#### `operation(x)`
56-
57-
Returns the function a function call expression is calling. `iscall(x)` must be
58-
true as a precondition.
59-
60-
#### `arguments(x)`
61-
62-
Returns the arguments to the function call in a function call expression.
63-
`iscall(x)` must be true as a precondition.
64-
65-
#### `maketerm(T, head, children, type=nothing, metadata=nothing)`
66-
67-
Constructs an expression. `T` is a constructor type, `head` and `children` are
68-
the head and tail of the S-expression, `type` is the `type` of the S-expression.
69-
`metadata` is any metadata attached to this expression.
70-
71-
Note that `maketerm` may not necessarily return an object of type `T`. For example,
72-
it may return a representation which is more efficient.
73-
74-
This function is used by term-manipulation routines to construct terms generically.
75-
In these routines, `T` is usually the type of the input expression which is being manipulated.
76-
For example, when a subexpression is substituted, the outer expression is re-constructed with
77-
the sub-expression. `T` will be the type of the outer expression.
78-
79-
Packages providing expression types _must_ implement this method for each expression type.
80-
81-
If your types do not support type information or metadata, you still need to accept
82-
these arguments and may choose to not use them.
83-
84-
85-
### Optional
86-
87-
#### `arity(x)`
88-
89-
When `x` satisfies `iscall`, returns the number of arguments of `x`.
90-
Implicitly defined if `arguments(x)` is defined.
91-
92-
93-
#### `metadata(x)`
94-
95-
Returns the metadata attached to `x`.
96-
97-
#### `metadata(expr, md)`
98-
99-
Returns `expr` with metadata `md` attached to it.
100-
101-
## Examples
102-
103-
### Function call Julia Expressions
104-
105-
```julia
106-
ex = :(f(a, b))
107-
@test head(ex) == :call
108-
@test children(ex) == [:f, :a, :b]
109-
@test operation(ex) == :f
110-
@test arguments(ex) == [:a, :b]
111-
@test isexpr(ex)
112-
@test iscall(ex)
113-
@test ex == maketerm(Expr, :call, [:f, :a, :b], nothing)
114-
```
115-
116-
117-
### Non-function call Julia Expressions
118-
119-
```julia
120-
ex = :(arr[i, j])
121-
@test head(ex) == :ref
122-
@test_throws ErrorException operation(ex)
123-
@test_throws ErrorException arguments(ex)
124-
@test isexpr(ex)
125-
@test !iscall(ex)
126-
@test ex == maketerm(Expr, :ref, [:arr, :i, :j], nothing)
127-
```
9+
[Read the documentation here.](https://juliasymbolics.github.io/TermInterface.jl/dev/)

‎docs/Project.toml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[deps]
2+
Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
3+
TermInterface = "8ea1fca8-c5ef-4a55-8b96-4e9afe9c9a3c"

‎docs/liveserver.jl

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
#!/usr/bin/env julia
2+
3+
# Root of the repository
4+
const repo_root = dirname(@__DIR__)
5+
6+
# Make sure docs environment is active
7+
import Pkg
8+
Pkg.activate(@__DIR__)
9+
using TermInterface
10+
11+
# Communicate with docs/make.jl that we are running in live mode
12+
push!(ARGS, "liveserver")
13+
14+
# Run LiveServer.servedocs(...)
15+
import LiveServer
16+
LiveServer.servedocs(;
17+
# Documentation root where make.jl and src/ are located
18+
foldername=joinpath(repo_root, "docs"),
19+
skip_dirs=[
20+
# exclude assets folder because it is modified by docs/make.jl
21+
joinpath(repo_root, "docs", "src", "assets"),
22+
],
23+
)

‎docs/make.jl

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
using Documenter
2+
using TermInterface
3+
4+
const TERMINTERFACE_PATH = dirname(pathof(TermInterface))
5+
6+
7+
makedocs(
8+
modules=[TermInterface],
9+
sitename="TermInterface.jl",
10+
pages=[
11+
"index.md"
12+
# "api.md"
13+
],
14+
checkdocs=:all,
15+
)
16+
17+
deploydocs(repo="github.com/JuliaSymbolics/TermInterface.jl.git")

‎docs/src/index.md

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# TermInterface.jl Documentation
2+
3+
This package contains definitions for common functions that are useful for symbolic expression manipulation.
4+
Its purpose is to provide a shared interface between various symbolic programming Julia packages, for example
5+
[SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl), [Symbolics.jl](https://github.com/JuliaSymbolics/Symbolics.jl) and [Metatheory.jl](https://github.com/0x0f0f0f/Metatheory.jl).
6+
7+
You should define the following methods for your expression tree type to work
8+
with TermInterface.jl, and therefore with [SymbolicUtils.jl](https://github.com/JuliaSymbolics/SymbolicUtils.jl)
9+
and [Metatheory.jl](https://github.com/0x0f0f0f/Metatheory.jl).
10+
11+
## Examples
12+
13+
### Function call Julia Expressions
14+
15+
```julia
16+
ex = :(f(a, b))
17+
@test head(ex) == :call
18+
@test children(ex) == [:f, :a, :b]
19+
@test operation(ex) == :f
20+
@test arguments(ex) == [:a, :b]
21+
@test isexpr(ex)
22+
@test iscall(ex)
23+
@test ex == maketerm(Expr, :call, [:f, :a, :b], nothing)
24+
```
25+
26+
27+
### Non-function call Julia Expressions
28+
29+
```julia
30+
ex = :(arr[i, j])
31+
@test head(ex) == :ref
32+
@test_throws ErrorException operation(ex)
33+
@test_throws ErrorException arguments(ex)
34+
@test isexpr(ex)
35+
@test !iscall(ex)
36+
@test ex == maketerm(Expr, :ref, [:arr, :i, :j], nothing)
37+
```
38+
39+
## API Docs
40+
41+
```@autodocs
42+
Modules = [TermInterface]
43+
```
44+

0 commit comments

Comments
 (0)